AIROC™ BTSTACK: Bluetooth® LE hello sensor for Linux host

This code example demonstrates Bluetooth® LE hello sensor functionality using AIROC™ Wi-Fi & Bluetooth® combo chip.

The application demonstrates a LE vendor-specific device. During initialization, the app registers with the LE stack to receive notifications such as bonding complete, connection status change, and peer write. When a device is successfully bonded, the application saves the peer's Bluetooth® device address to its NVRAM. Bonded devices can also write into the client configuration descriptor of the notification characteristic. That is also saved in the device's NVRAM. When the user chooses the option to send notification, it is sent to the bonded and registered client. The user can also write to the characteristic configuration value.

View this README on GitHub.

Provide feedback on this code example.

Requirements

• Programming language: C
• Embedded Linux Host platforms (Arm® Cortex®-A Class processors). Supported Embedded Linux host platforms:
  1. RPI CM4-lite with custom HW base board from Infineon
  2. IMX8 nano uCOM board from Embedded Artists
  3. Jetson Xavier board from NVIDIA
• AIROC™ BTSTACK library and Linux porting layer source code
• AIROC™ Wi-Fi & Bluetooth® combo chip Bluetooth® Firmware file (.hcd).
• Linux Host PC with Ubuntu 20.04

Supported toolchains (make variable 'TOOLCHAIN')

• GNU Arm® GCC Arch64 v9.3.0 (GCC_ARM)

Supported AIROC™ Wi-Fi & Bluetooth® combo chip

• AIROC™ CYW5557x Wi-Fi & Bluetooth® combo chip

Hardware setup

Set up the hardware according to Figure 1:

Figure 1. Block diagram: Hardware setup

Software setup

Set up a cross compiler according to the target platform along with CMake on the Linux host PC based on Ubuntu 20.04.1.

1. Open a terminal on the Linux host PC.

2. Use the following command to install the cross compiler, build tools, and dependencies:

   sudo apt-get install git cmake gcc-aarch64-linux-gnu build-essential -y

Using the code example

Do the following on the Linux host PC to compile the code example:

1. Create a directory under $HOME on the Linux host PC and switch to the created directory. For example, use the following commands to switch:

   mkdir $HOME/Linux_CE
   cd $HOME/Linux_CE

2. Fetch the code example source code from GitHub.

   git clone https://github.com/Infineon/linux-example-btstack-hello-sensor

3. Clone the code example dependencies (BTSTACK library and Linux porting layer source code) using the following commands:

   git clone https://github.com/Infineon/btstack.git --branch release-v3.6.0
   git clone https://github.com/Infineon/bluetooth-linux.git --branch release-v1.0.0

   Three different directories are created after cloning the code example and its dependencies as shown in the Figure 2.

   Figure 2. Code example directory structure

   

4. Clone the Bluetooth® firmware using following command.

   git clone https://github.com/Infineon/combo-bluetooth-firmware.git

   User can choose appropriate Bluetooth® firmware for particular AIROC™ Wi-Fi & Bluetooth® combo chip from cloned "combo-bluetooth-firmware" directory.

5. Create the build folder under the code example source folder and build the code example using the following commands:

   cd $HOME/Linux_CE/linux-example-btstack-hello-sensor
   mkdir build && cd build
   cmake -DCMAKE_C_COMPILER:PATH=<GCC_CROSS_COMPILER> ../ && make
   

   Where,

   • GCC_CROSS_COMPILER is the target cross compiler for GCC (generally /usr/bin/aarch64-linux-gnu-gcc for ARM64-based targets)

   The code example executable is generated under the build folder with the same name of code example.

   For example, in this project, the "linux-example-btstack-hello-sensor" executable is generated at /home/$USER/Linux_CE/linux-example-btstack-hello-sensor/build.

Features demonstrated

• GATT database and device configuration initialization
• Registration with the LE stack for various events
• NVRAM read/write operations
• Sending data to the client
• Processing write requests from the client

Operation

This code example acts as a GATT server and LE peripheral. The remote device will be a GATT client and LE central device.

Two devices are required to demonstrate this application: One hardware platform (Linux host platform + AIROC™ Wi-Fi & combo chip, i.e., the device running the Hellosensor application) and a GATT client application on mobile or laptop.

1. Take SSH console of target platform.

   ssh <TARGET_DEVICE_USER_NAME>@<TARGET_DEVICE_IP_ADDRESS>

2. Copy the code example executable and AIROC™ BTSTACK library from the Linux host PC to the target platform using SCP. For example, use the following commands:

   cd $HOME/Linux_CE/linux-example-btstack-hello-sensor/build
   scp linux-example-btstack-hello-sensor <TARGET_USER>@<TARGET_IP>:<TARGET_PATH>/.
   cd $HOME/Linux_CE/btstack/stack/COMPONENT_WICED_DUALMODE/COMPONENT_ARMv8_LINUX/COMPONENT_GCC
   scp libbtstack.so <TARGET_USER>@<TARGET_IP>:<TARGET_PATH>/.
   scp <FW_FILE.hcd> <TARGET_USER>@<TARGET_IP>:<TARGET_PATH>/.
   

   Where,

   • TARGET_USER is the user name of the target platform
   • TARGET_IP is an IP address of the target platform
   • TARGET_PATH is the path of target platform
   • FW_FILE.hcd file is Bluetooth® Firmware file cloned in Using the code example section.

3. Add the udev rule in the target host board for HCI UART and GPIO to bypass root access. Use the following steps to create and set up a udev rule.

   Note: If you have root access, the following udev rules are not required; you can execute the code example with sudo permissions or by switching to the root user.

   1. Create a new .rules (for example, combo-chip-uart-port.rules) file under /etc/udev/rules.d/ directory for HCI UART. Use the following commands:

      IMX8Nano:

      echo "KERNEL==\"ttymxc0\"d,SYMLINK+=\"combo_chip_uart\",MODE=\"0666\"" | sudo tee /etc/udev/rules.d/combo-chip-uart-port.rules

      RPICM4:

      echo "KERNEL==\"ttyAMA0\",SYMLINK+=\"combo_chip_uart\",MODE=\"0666\"" | sudo tee /etc/udev/rules.d/combo-chip-uart-port.rules

      Jetson Xavier:

      echo "KERNEL==\"ttyTHS1\",SYMLINK+=\"combo_chip_uart\",MODE=\"0666\"" | sudo tee /etc/udev/rules.d/combo-chip-uart-port.rules

   2. Create new .rules (for example, combo-chip-gpio-port.rules) for BT_REG_ON GPIO under /etc/udev/rules.d/. Use the following commands:

      IMX8Nano & RPICM4:

      1. Create a rule file using the following command.

         sudo vim /etc/udev/rules.d/combo-chip-gpio-port.rules.rules

      2. Add the following rules in created files:

         SUBSYSTEM=="gpio*", PROGRAM="/bin/sh -c 'chown -R $user:$group /sys/class/gpio/export /sys/class/gpio/unexport;'"
         SUBSYSTEM=="gpio*", PROGRAM="/bin/sh -c 'chown -R $user:$group /sys%p/direction /sys%p/value; chmod 660 /sys%p/direction /sys%p/value;'"

      Jetson Xavier:

      1. Create a rule file using the following command:

         sudo vim /etc/udev/rules.d/combo-chip-gpio-port.rules.rules

      2. Add the following rules in the created files:

         SUBSYSTEM=="gpio*", PROGRAM="/bin/sh -c 'chown -R ifx:gpio /dev/gpiochip0; chmod -R 770 /dev/gpiochip0;'"
         SUBSYSTEM=="gpio*", PROGRAM="/bin/sh -c 'chown -R ifx:gpio /dev/gpiochip1; chmod -R 770 /dev/gpiochip1;'"

   3. Reboot the target device:

      sudo reboot

      Where,

      • ttyTHS1, ttymxc0, and ttyAMA0 are HCI UART ports for Jetson Xavier, IMX8Nano and RPICM4 respectively
      • combo_chip_uart is a friendly name for the HCI UART port
      • 0666 is the permission mask to bypass the root access for HCI UART

4. Execute the application by setting the paths of the AIROC™ BTSTACK library using the following command on the target platform:

   cd <TARGET_PATH>
   chmod +x <APP_NAME>
   LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<BTSTACK_LIB_PATH>
   ./<APP_NAME> -c <COM_PORT> -b 3000000 -f 921600 -r <GPIOCHIPx> <REGONPIN> -n -p <FW_FILE_NAME>.hcd -d 112233221144
   

   Where,

   • TARGET_PATH is the path of the target platform where the code example application copied to

   • BTSTACK_LIB_PATH is the path of the AIROC™ BTSTACK library. Skip this if the AIROC™ BTSTACK library and code example application executable are in the same folder

   • /dev/ttyTHS1 is the COM_PORT for Jetson Xavier

   • /dev/ttymxc0 is the COM_PORT for IMX8Nano

   • /dev/ttyAMA0 is the COM_PORT for RPICM4

   • 3000000 is the HCI baud rate

   • 112233221133 is a device BD address

   • -r <GPIOCHIPx> <REGONPIN> -n is setting the GPIO control to program the Bluetooth® Firmware for AIROC™ Wi-Fi + Bluetooth® combo chip

     • -r gpiochip5 0 -n For IMX8Nano
     • -r gpiochip0 3 -n For RPICM4
     • -r gpiochip1 16 -n For Jetson Xavier

   • 921600 is the firmware patch download baud rate

   • .hcd is the firmware patch to download (make sure to validate this firmware patch file path)

     Note 1: If you haven't set up a udev rule mentioned in Step 4, execute the command with sudo permissions.

     Note 2: Currently, random BD addresses are used for testing.

   Wait for the download hcd file message from the console.

   ...
   Download pathfile <FW-FILE-NAME>.hcd
   ...
   patch_download_complete
   ...
   Patch successfully downloaded. Reset chip
   

5. To test using LightBlue iOS/Android app on a smartphone as Bluetooth® LE Central, do the following:

   1. Download and install the LightBlue app for iOS or Android.

      Scan the following QR codes from your mobile phone to download the LightBlue app.

      Figure 3. Application QR code

      

   2. Turn ON Bluetooth® on your Android or iOS device and launch the LightBlue app and Swipe down on the LightBlue app home screen to start scanning for Bluetooth® LE Peripherals; your device appears in the LightBlue app home screen with the name 'Hello'. Select your device and to establish a Bluetooth® LE connection (see Figure 4) and accept the pairing request.

      Figure 4. Scan and connect 'Hello' using LightBlue app

      

   3. After Bluetooth® connected, you can see multiple Serivces: Device Information, Battery Service and UUID:1B7E8251-2877-41C3-B46E-CF057C562023 (see Figure 5).

      Figure 5. hello app service and characteristic list

      

   4. Select 0x5E9BF2A8-F93F-4481-A67E-3B2F4A07891A Characteristic and then select the characteristic with the Write property, write 1 byes only, you can see the value will be change by written value. (see Figure 6)

      Figure 6. test write property through app

      

Debugging

You can debug the example using the following generic Linux debugging mechanism:

• Debugging by logging: You can add prints in the application and check it during execution.

• Debugging using GDB: See GDB man page for more details.

Design and implementation

This code example does the following:

1. Parses the command-line arguments.

2. Initializes the AIROC™ BTSTACK library for the Airoc Combo Chip.

3. Advertises the Hello Sensor service characteristics, as depicted in the following image, along with device information and other services.

Figure 4. Hello sensor service characteristics

The LE GATT client performs service discovery using the "GATT Discover All Primary Services" procedure. The Bluetooth® LE service characteristic discovery is done by the "Discover All Characteristics of a Service" procedure. When the GATT client chooses 'Unknown Service' (Hello Sensor service is a vendor-specific service), two characteristics are displayed: Notify and Blinks (both are displayed as unknown).

The LE GATT client can choose to get notifications on the 'Notify' whose value is 'Hello 0' or write to the 'Blinks' with the value desired. The number of blinks is stored at the server and prints on the console.

Every time the user presses the Enter key, the number of blinks is displayed on the console and the notify value is also notified to the client with 'Hello 1' (the last byte increments every time the user chooses to notify).

Figure 5. Hello sensor process flowchart

4. Waits until interrupted or closed.

Resources and settings

Table 1. Application resources

Resource	Alias/object	Purpose
UART	HCI	UART is used for HCI communication with host system

Related resources

Resources	Links
Device documentation	AIROC™ CYW5557x Wi-Fi 6E tri-band Wi-Fi and Bluetooth® 5.2 SoC
AIROC™ BTSTACK library	AIROC™ BTSTACK library
Linux porting layer source code	Linux porting layer source code

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: CE236727 – AIROC™ Airoc Combo Chip: Bluetooth® LE hello sensor using embedded Linux platforms

Version	Description of change
1.0.0	New code example

---

© Cypress Semiconductor Corporation, 2022. 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, WICED, 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 cypress.com. Other names and brands may be claimed as property of their respective owners.