Skip navigation
Home > All Places > ModusToolbox > Blog > Authors GyanC_36

ModusToolbox

2 Posts authored by: GyanC_36 Moderator

Objective:

This blog post discusses implementation of BLE Proximity Profile in  CYW20819 using the device configurator tool in ModusToolBox IDE.

Requirment:

Tool: ModusToolBox 1.1 or above, Serial Terminal (Example: TeraTerm, CoolTerm)

Programming Language: C

Associated Parts: CYW20819

Related Hardware: CYW920819EVB-02 Board (2 boards required)

Proximity Profile:

The purpose of proximity profile is to keep an eye on the BLE Connection link between two devices and trigger an alert when the link is weakened as path loss increases. This profile supports two roles:

  1. Proximity Server (Reporter)
  2. Proximity Client (Monitor)

The proximity profile must include the Link Loss Service. It may optionally include Tx Power Service and Immediate alert service also. Link Loss Service:  The GATT DB of the link loss service has the “Alert Level” characteristic which may be written by the proximity client. This indicates the level of alert to be triggered in the server when the disconnection happens.Tx power Service:  The proximity client may anytime know the Transmitter Power level of the server. This is enabled by reading the Tx Power level characteristic included in the Tx power service.Immediate Alert Service:  The proximity monitor may keep calculating the path loss as follows:

Path Loss = Tx Power Level – RSSI

If the path loss exceeds a certain threshold, the monitor may write the Alert Level characteristic of the IAS, thereby prompting the user to perform appropriate action to avoid disconnection.

Block Diagram:


Using the Device Configurator to generate Proximity Server project:

We can use the Device Configurator Tool in ModusToolBox IDE to generate the GATT DB and an outline code for the firmware. For more details on using the Device Configurator, refer to the Bluetooth Designer Guide in WICED Studio SDK. The GATT DB of the Proximity Server has 3 different services. It is easy to generate the GATT DB and a skeleton code using the Bluetooth Device Configurator Tool.

  1. In the ModusToolBox IDE, go to project folder -> design.modus-> Device Configurator.
  2. Select ‘Bluetooth’ and Click on ‘Launch Bluetooth Configurator’.

      

       3. Using the “Add Service” Option, different services are selected.

        

       4. Add the characteristics as shown above and save the configuration to obtain the skeleton project. The files will be


Firmware: This example contains two projects – The proximity server and the proximity client. Proximity Server:  A skeleton code of the proximity server can be generated using the above steps. Certain key features need to be added to the skeleton code to make the server project complete. According to the specification, a proximity reporter has to advertise with the UUID of Link Loss Service. So, the advertisement data should be modified as follows

 

:/* Set Advertisement Data */

void proximityserver_set_advertisement_data( void )

{    wiced_bt_ble_advert_elem_t adv_elem[3] = { 0 };

    uint8_t adv_flag = BTM_BLE_GENERAL_DISCOVERABLE_FLAG | BTM_BLE_BREDR_NOT_SUPPORTED;

    uint8_t num_elem = 0;
    /* Advertisement Element for Flags */

adv_elem[num_elem].advert_type = BTM_BLE_ADVERT_TYPE_FLAG;

adv_elem[num_elem].len = sizeof(uint8_t);

adv_elem[num_elem].p_data = &adv_flag;

num_elem++;


adv_elem[num_elem].advert_type  = BTM_BLE_ADVERT_TYPE_16SRV_COMPLETE;

adv_elem[num_elem].len = sizeof(lls_uuid);

adv_elem[num_elem].p_data       = ( uint8_t* )lls_uuid;

   num_elem++;


    /* Advertisement Element for Name */

adv_elem[num_elem].advert_type = BTM_BLE_ADVERT_TYPE_NAME_COMPLETE;

adv_elem[num_elem].len = strlen((const char*)BT_LOCAL_NAME);

adv_elem[num_elem].p_data = BT_LOCAL_NAME;

num_elem++;


    /* Set Raw Advertisement Data */

wiced_bt_ble_set_raw_advertisement_data(num_elem, adv_elem);

}


Where lls_uuid is declared and initialized as:

/* Link Loss service UUID  */

const uint8_t lls_uuid[2] = {(uint8_t)UUID_SERVICE_LINK_LOSS & 0xFF, (uint8_t)(UUID_SERVICE_LINK_LOSS >> 8)  };


The proximity server receives Link Loss and IAS Alerts in the form of writes. The IAS Alert is triggered instantaneously whereas the link loss alert happens when there is a disconnection. The Alerts are indicated by the LEDs. Proximity Client:  This is a central / client device that performs read / write operations with the GATT DB of the server. The central starts scanning for peripherals that advertise with a Link Loss Service UUID, upon a GPIO button press and initiates the connection. Then it begins to discover all the three services of the proximity profile in the server, one by one and saves the handles of the attributes. Following this, the TX power characteristic of the server is read. Now the client periodically calculates the RSSI every 100 mS and thus the average path loss. If the path loss reaches beyond certain thresholds, the client writes to the Immediate alert characteristics of the server, resulting in an immediate trigger. The thresholds are as follows: MILD ALERT: Path loss above 90 dB HIGH ALERT: Path loss above 100 dBThe Link loss alert can be written to the server by pressing the GPIO Interrupts on the client Eval Board. Every time the GPIO is pressed, a different LL alert value is written to the server.


Programming and Testing:

  1. Install the ModusToolBox 1.1 (or above) in your PC. Plug in two CYW920819EVB-02 Boards and let the drivers bind to the devices. Make sure the jumpers are in place. For more details, please refer Getting Started with CYW20819.
  2. Refer this Knowledge Base Article for importing a new ModustoolBox Project.
  3. Open two windows of Serial Terminal (Example: Teraterm or Coolterm), and bind each of those windows to the PUART COM Ports of each devices. Each device has two COM Ports with consecutive numbers. The COM Port with the bigger number corresponds to the PUART that displays Debug Messages. The one with the smaller number corresponds to the HCI UART. The BaudRate is set to 115200 in the firmware. Make sure the BaudRate in serial terminals is also set to 115200.
  4. Select the proximity_server project you created, and click on ‘Build and Program’ as shown in below figure. You can see the Secure_hub program being built and downloaded into one of the boards. (For more details or troubleshooting, please refer the Getting Started with CYW20819)

       

       

  1. Similarly program the ProximityClient program to the device.
  2. The ProximityServer device will start to advertise. In the ProximityClient device, press the BTN (D2) button for more than 5 seconds for the scan to start. Once the ProximityClient finds the ProximityServer device advertising, it will automatically initiate connection and pairing process.
  3. The client performs discovery in the server and saves the attribute handles of the Link loss alert, immediate alert and transmit power characteristics. The initial Tx power is also read from the server.
  4. Click the BTN (D2) button to write LL Alert value to the server. Every time the button is pressed, a different value of alert level (among the 3: NO_ALERT, MILD_ALERT, HIGH_ALERT) is written to the server. When a link loss happens, the server will be triggered based on the alert level that was written, as indicated by the LED 2.
  5. The client will also keep calculating the Path loss and writes immediate alerts to the server if the path loss value exceeds a certain threshold. Such alerts immediately trigger the server, as indicated by the LED 1.


Path Loss Vs Distance:

 

For a Tx Power of 4 dBm in CYW20819, the path loss Vs Distance values are observed as below in an office environment

 

 

  

Related Documents:

The below table lists all relevant application notes, code examples, knowledge base articles, device datasheets, and Component / user module datasheets.

 

Document

Title

Comment

002-25684

AN225684 - Getting Started with CYW20819

The Getting Started Guide can be downloaded from here.

002-26340

CYW920819EVB-02 Evaluation Kit User Guide

This Evaluation Kit User Guide can be downloaded from here.

Objective:

This example demonstrates the implementation of different security levels of pairing and the data transfer in a multi-connection environment.

 

Overview:

This project instantiates a data hub that plays the roles of GAP Central, GAP Peripheral, GATT Client and GATT Server at the same time, and that is able to pair with up to 3 slaves at different security levels. In addition, the device will also be able to pair with a Master, to which it can send the data collected from the slaves or distribute the data from the master to the slaves.


Requirements:

Tool: ModusToolBox IDE 1.1 and above, Any BLE Central (Example: CySmart Mobile Application), Serial Terminal (Example: TeraTerm, CoolTerm)

Programming Language: C

Associated Parts: CYW20819

Related Hardware: CYW920819EVB-02 Board (2 to 4 required)

 

Block Diagram:

                                                  Figure 1: Block Diagram

 

          

As shown in the above block diagram, the Secure Hub can connect with up to 3 slave devices (programmed with hello_sensor project). It in turn serves as a slave for a master device. All the CYW20819 devices will be able to communicate with the PC via PUART interfaces that appear as serial terminal COM Ports in the PC.

 

Firmware Flow of secure_hub Device:

 

                                                                              Figure 2: Firmware Flow

                

 

 

  • application_start is the program entry point. Here the peripheral UART is set for displaying Debug Messages. The BT Stack and the corresponding management callback are started using the wiced_bt_stack_init () API.
  • db_management_cback()  function in secure_hub.c handles the events generated for the BLE Stack. The BTM_ENABLED_EVT indicates that the Bluetooth stack is ready. Upon the reception of this event, we start the Non-Connectable High Duty Cycle advertisement. The Timer and GPIO Interrupts are registered. The Timer and GPIO Button Press Interrupt callbacks increment the suffix in the Device Name by 1 and then continues the advertisement with the incremented name.
  • In the secure_hub and the hello_sensor projects, the user needs to enter the desired security level and IO Capabilities via console. The console accepts inputs via PUART. The 4 security levels supported in this project are
  1. Just Works
  2. MITM
  3. LE Secure Connection
  4. LE Secure Connection with MITM
  • The hello_sensor project starts advertising, once these details are entered. A Scan is initiated via GPIO Interrupt button press on the secure_hub device. The UUID of the service available in the hello_sensor node is verified in the callback, after which the connection is initiated by the secure_hub.
  • Once a connection is established with the slave, the secure_hub performs a GATT Discovery of the slave using the custom UUIDs of hello_service. The discovery happens in 3 stages:

                 (i)Service

                (ii) Characteristic

                (iii) Descriptor

 

GATT DB:

The GATT DB of the hello_sensor device contains the hello service. The hello_service contains two characteristics (Refer hello_sensor/gatt_db.c and hello_sensor/gatt_db.h files)

  • HANDLE_HSENS_SERVICE_CHAR_NOTIFY:This characteristic has the properties of Notification and Indication. The Bytes to be notified    / indicated are typed in the serial terminal of the hello_sensor device and are transmitted as Notification or Indication to the secure_hub.
  • HANDLE_HSENS_SERVICE_CHAR_BLINK:This characteristic has the properties of Read and Write. The secure nature of the application is demonstrated using this characteristic. In the gatt_db.c file of the hello_sensor, it can be noticed that the permissions of this characteristic include these bitmasks: LEGATTDB_PERM_WRITE_REQ| LEGATTDB_PERM_AUTH_WRITABLE. This means that this characteristic can be written only when the link has been paired with MITM (Man in the middle protection).  Security Levels (either BTM_LE_AUTH_REQ_MITM or BTM_LE_AUTH_REQ_SC_MITM. The user has to manually take care of this in the application level. When other security levels are used, a write to this characteristic will result in an “Insufficient Authentication” error. Once this characteristic is successfully written by a one byte value, the Red LED on the board blinks as many times as the written value. By the end of the discovery, the secure_hub device stores the Attribute handles of the HANDLE_HSENS_SERVICE_CHAR_BLINK characteristic and the CCCD (Client Characteristic Configuration Descriptor) of the HANDLE_HSENS_SERVICE_CHAR_NOTIFY characteristic. With the attribute handles, the secure_hub device can write to these characteristics descriptors. The CCCD Handle is required, so that the notifications / indications can be enabled / disabled on the hello_sensor slaves. The handles are stored in a global structure g_secure_hub.
  • The GATT DB of the secure_hub device correspondingly has two characteristics HANDLE_SECURE_HUB_SERVICE_CHAR_NOTIFY and HANDLE_SECURE_HUB_SERVICE_CHAR_LED_WRITE. The former is used to transmit the Notifications / Indications received from the hello_sensor devices to the master (if present any). Such notifications are appended along with the Connection ID of the slave, so that the master can identify the slave that has sent the notification. The latter is used to receive writes from the master, which is in-turn written to the HANDLE_HSENS_SERVICE_CHAR_BLINK characteristic on the hello_sensor slaves.
  • At any instant, a new slave may be connected to the secure_hub or a old one may detach itself by pressing the SW1 button the board. A maximum of 3 hello_sensor slaves can be connected to the secure_hub device at a time, in addition to a master. The secure_hub keeps advertising, until a master has connected to it. It will again start advertising when the master has disconnected from it.

 

Programming and Testing:

  • Install the ModusToolBox 1.1 (or above) in your PC. Plug in two CYW920819EVB-02 Boards and let the drivers bind to the devices. Make sure the jumpers are in place. For more details, please refer Getting Started with CYW20819.
  • Refer this Knowledge Base Article   for importing a new ModustoolBox Project.
  • Open two windows of Serial Terminal (Example: Teraterm Coolterm), and bind each of those windows to the PUART COM Ports of each devices. Each device has two COM Ports with consecutive numbers. The COM Port with the bigger number corresponds to the PUART that displays Debug Messages. The one with the smaller number corresponds to the HCI UART. The BaudRate is set to 115200 in the firmware. Make sure the BaudRate in serial terminals is also set to 115200.
  • Select the secure_hub project you created, and click on ‘Build and Program’ as shown in below figure. You can see the Secure_hub program being built and downloaded into one of the boards. (For more details or troubleshooting, please refer the Getting Started with CYW20819)

 

      

  • Similarly program the hello_sensor firmware to another device.
  • In the Teraterm, the debug logs can be seen asking to select the security level among these 4 – No Security, MITM (Man in the middle), LE Secure Connection, LE Secure Connection with MITM. Select the appropriate security level on either device, by entering the corresponding number. Following this, for the security levels that involve MITM, you will have to select the IO Capabilities. The user has to select the MITM.

 

           

          

  • The hello_sensor device will start to advertise. In the secure_hub device, press the SW3 button for more than 5 seconds for the scan to start. Once the secure_hub finds the hello_sensor device advertising, it will automatically initiate connection and pairing process. In case of the security levels with MITM, passkey entry might be required, where the user has to enter the passkey displayed by one device as input to another device.
  • The secure_hub device keeps advertising and it can be connected to another central (any BLE App on Smart Phone, say CySmart.)
  • Once the pairing is complete, the secure_hub automatically enables notifications on the hello_sensor device. The user will be able to send notifications by directly typing on the terminal of the hello_sensor byte by byte. The secure_hub displays the notifications received from the hello_sensor and in turn sends them to the Central if present, and if notifications / indications have been enabled by the Central.
  • At any time, another hello_sensor device can be connected the secure_hub by following steps 7,8,9 while preserving the existing connection. A maximum of 3 hello_sensor devices can be connected to the secure hub.
  • The Central can send write requests to the secure_hub which in turn performs write requests to the slave hello_sensor devices connected to it.

Note: When the secure_hub tries to write to a slave with which it has paired with security levels without MITM, it will receive “Insufficient Authentication Error”. Also, when the master tries to write to the secure_hub, when no slaves are connected to the secure_hub, it will result in an “insufficient authorization” error.

 

Related Documents:

Table -1 lists all relevant application notes, code examples, knowledge base articles, device datasheets, and Component / user module datasheets.

 

Table 1: Related Documents

 

Document

Title

Comment

002-25684

AN225684 - Getting Started with CYW20819

This Getting Started Guide can be downloaded from here.

002-26340

CYW920819EVB-02 Evaluation Kit User Guide

This Evaluation Kit User Guide can be downloaded from here.