Skip navigation
Home > All Places > WICED Studio Bluetooth > WICED Studio Bluetooth Forums > Blog > Authors madhul_36

This blog post discusses implementation of BLE Proximity Profile in CYW20719 and CYW20735 using the Bluetooth Designer tool of WICED Studio SDK.

Requirment:

Tool: WICED studio 6.2, Serial Terminal (Example: TeraTerm, CoolTerm)

Programming Language: C

Associated Parts: CYW20719 / CYW20735

Related Hardware: CYW920719Q40EVB_01 Board (1 or 2) / CYW920735Q60EVB_01 (1 or 2)

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 Bluetooth Designer to generate Proximity Server project:

We can use the Bluetooth Designer in WICED Studio SDK to generate the GATT DB and an outline code for the firmware. For more details on using the Bluetooth Designer, 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 Designer Tool. (For more details on the Bluetooth Designer tool, please refer the user guide which can be accessed in the WICED Studio from Project Explorer -> <Platform> -> Doc

  1. In the WICED Studio SDK, go to File -> New -> WICED Bluetooth Designer. Enter the device name as “ProximityServer”, mode as Single Mode LE.
  2. Check the GATT DB enabled option Click Next.
  3. Using the “Add Service” Option, different services are selected.
  4. Add the characteristics as shown above and click “Generate Code” to obtain the skeleton project.


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 where as 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. Everytime the GPIO is pressed, a different LL alert value is written to the server. 


Programming and Testing:

 

  1. Install the WICED Studio 6.2 (or above) in your PC. Plug in two CYW920719Q40EVB_01 Boards and let the drivers bind
  2. to the devices. Make sure the jumpers are in place. Open WICED Studio and set the platform as 20719-B1_Bluetooth. For more details, please refer CYW920719Q40EVB_01-Kit-Guide.pdf present in Doc folder in the project explorer.
  3. Copy the ProximityServer and the ProximityClient folders. In the WICED Studio, right-click the Apps folder in the Project Explorer pane and click Paste. You can see these folders under the Apps folder.
  4. 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.
  5. Create a Make Target for the project by selecting Project -> Make Target -> Create. Paste the following as the entry in the Target Name field:

ProximityServer-CYW920719Q40EVB_01 UART=COMxx download

Make sure that the Same as the Target Name checkbox is checked. Click OK. Create another target, in addition to the previous one as:

ProximityClient-CYW920719Q40EVB_01 UART=COMyy download

(Note: In the above targets, XX and YY are the PUART COM Port numbers of each of the devices)

    6. Double click the ProximityServer Target you just created, shown in the Make Target Pane on the right. You can see the Secure_hub program being built and downloaded into one of the boards.

     7.  Similarly program the ProximityClient program to the device.

     8. 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.

     9. 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.

     10. Click the BTN (D2) button to write LL Alert value to the server. Everytime 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.

     11. 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 CYW20719 and of 12 dBm in CYW20735, the path loss Vs Distance values are observed as below in an office environment.

CYW20719:

 

  

CYW20735:

 

Distance (m)

Path Loss (dBm)

0

12

0.01

20

0.02

30

1

50

2

60

5

70

7

80

10

93

15

95

20

96

25

97

30

98

40

99

50

100

80

101

100

102

120

104

140

105

160

107

180

107

200

108

210

109

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-22816

CYW920719Q40EVB-01 Evaluation Board User Guide

The  User Guide can be accessed in the WICED Studio from Project Explorer -> 20719-B1_Bluetooth -> Doc

002-19103

Developing Custom Applications with BT Designer - Document

This document can be accessed from Project Explorer -> <Platform> -> Doc

madhul_36

Cypress BLE Mesh Solution

Posted by madhul_36 Jan 8, 2018

Disclaimer: BLE mesh solution in WICED Studio 6.1 and WICED Studio 6.2 is meant only for evaluation. Limited testing is done for BLE mesh in these releases. Cypress community won't provide any support for BLE mesh until the solution is officially rolled out for the broad market.

 

The Cypress BLE Mesh Solution is fully compliant with the Bluetooth SIG's Mesh Specification and is certified. It is available on WICED studio 6.1 SDK.

 

Part Numbers supported: CYW20706, CYW20719B1

Modules available: CYBT-343026-01 (Based on CYW20706 chip)

Eval Boards: CYBT-343026-EVAL (Based on the CYBT-343026-01 module), CYW920706WCDEVAL based on CYW20706 chip, CYW920719Q40EVB-01 (Based on CYW920719WCD1 module)

Bluetooth Specification: 5.0

Mesh Specification: 1.0

 

The WICED Studio SDK has resources that help in getting started with the BLE Mesh Solution by providing examples projects for all the SIG defined models specified in the Mesh Model Specification 1.0

 

The Mesh firmware examples are available in the WICED Studio in the location: WICED-Studio-6.1\<Platform>\apps\snip\mesh. The Mesh usecase requires a provisioner that creates the network, provisions, configures and control devices of the network. This provisioner can be realized using Cypress's MeshLighting App for Android (located in WICED-Studio-6.1\common\apps\snip\mesh\peerapps\Android\src\bin) or the windows ClientControlMesh Application.

 

Provisioning using MeshLighting Android Application:

 

1) Connect the Eval Board to the PC and load the mesh_onoff_server project. Refer to the corresponding Kit User Guide for details on programming the firmware. Once programmed, the device advertises as an unprovisioned mesh device.

 

2) Copy the apk file of the MeshLighting app to your android phone, install the application and open it.

 

3) In the Options, select "Create Network" and specify a name, say "TestNetwork".

 

Screenshot_2018-01-29-17-13-30-377_com.cypress.le.mesh.meshapp.pngScreenshot_2018-01-25-14-22-54-109_com.cypress.le.mesh.meshapp.png

4) Now you can add your own Rooms in the network. A room is a group of devices that form a part of the whole network, to which commands can be multicasted using a single address. Tap the + icon to add a room and specify a name, say "New Room".

Screenshot_2018-01-25-14-23-23-919_com.cypress.le.mesh.meshapp.png Screenshot_2018-01-25-14-23-53-322_com.cypress.le.mesh.meshapp.png

 

 

5) Tap the ADD DEVICE option to scan for of unprovisioned mesh devices. Once the device is detected, click OK to start the provisioning and also configures the device through series of messages sent to the on/off device. The proxy connection is establish with the first device by default. If the proxy disconnects for some reason, the user can tap the "Connect to proxy" and "Configure" buttons to resume the proxy connection and configuration.

 

6) Repeat step 4 to add any number of other devices to the room. Now we can control the ON/OFF status of the devices in the room by sliding the  ON/OFF switch. We can also specify the transition time. The proxy receives the message and transmits it to the nodes in the network. The change of state in the devices may be indicated by the UART Prints and a LED toggle on the board.

 

Screenshot_2018-01-25-21-51-32-483_com.cypress.le.mesh.meshapp.png

 

7) After receiving the messages, the devices send status, which is displayed in the Phone as shown below:

 

Screenshot_2018-01-25-21-57-29-849_com.cypress.le.mesh.meshapp.png

 

8) Instead of the mesh_onoff_server example, the mesh_light_hsl_server example can also be used with the App. The App can now modify the Color of the light (By setting Hue, Saturation and Lightness values). The Color setting in the GUI can now be accessed as below.

 

Screenshot_2018-02-09-19-14-53-232_com.cypress.le.mesh.meshapp.pngScreenshot_2018-02-09-19-14-58-481_com.cypress.le.mesh.meshapp.png

 

WICED Studio also provides an example for mesh_onoff_client which acts as a switch for the mesh_onoff_server devices. The device can be provisioned into the network using the App. Upon configuration, the device will be listed as a switch. In the below figure the light1 is a provisioned mesh_onoff_client device and the light2 is a mesh_onoff_server project as indicated by icons.

 

Screenshot_2018-02-15-19-17-54-320_com.cypress.le.mesh.meshapp.png

 

Tap on the light1 to see options for assigning light2 to the switch.

 

Screenshot_2018-02-15-19-18-00-295_com.cypress.le.mesh.meshapp.pngScreenshot_2018-02-15-19-18-09-904_com.cypress.le.mesh.meshapp.png

 

Provisioning using windows ClientControlMesh Application:

 

The ClientControlMesh Application for windows is located in "WICED-Studio-6.1\common\apps\snip\mesh\ClientControl\Release". This application sends WICED HCI commands to devices via HCI UART. This app can be used to perform provisioning by sending commands to an embedded mesh controller device that acts as a provision client. A provisioning client can be realized using the mesh_provision_client example firmware in the SDK. The ClientControlMesh tool sends Mesh events as WICED HCI commands. So make sure the C_FLAGS += -DHCI_CONTROL flag is enabled in the makefile.mk in your project.

 

1) Connect an Eval board to the PC and load the mesh_provison_client example to it.

 

2) Open the ClientControlMesh Application and choose the Light Control Tab. and select the HCI UART COM Port number of the provision client device in the GUI.

 

3) Click the "Open" button. This will configure the provision client device, as shown by the series of messages in Trace box in the bottom.

 

4) Click "Create" button to add a network and name it as say, "TestNetwork"

 

4) Connect one more Eval board to the PC and load the mesh_onoff_server or mesh_level_server or mesh_hsl_server example. The device will advertise as an unprovisioned mesh device.

 

5) Click the "Scan Unprovisioned" button. The provision client will scan for the unprovisioned device and lists the details.

 

6) Click "Stop Scanning" and then "Provision and Configure" buttons. The mesh device will be added to the "TestNetwork" after provisioning and configuration.

 

7) Now commands can be sent and status can be received using the tools in the bottom pane of the ClientControlMesh App. In the figure shown below, the "OnOff serve (0002)" device has been provisioned and the On/Off state of the light can be changed using the Get and Set buttons.

 

8) Repeat steps 4,5,6,7 to add more devices to the network and control them.

 

cc5.png

 

The ClientControlMesh App can also be used to control switches (say, mesh_Onoff_Client, mesh_hsl_client, mesh_level_client devices) by sending WICED HCI commands.

 

1) Create a network, provision a switch and a light using a provisioner (say MeshLighting Android App or Mesh_provision_client by following the above guidelines.

2) In ClientControl.exe and select the HCI UART COM Port number of the Switch device (say, mesh_onoff_client) in the GUI.

2) Open Models tab.

3) Choose "onoff" from dropdown.

4) Check the "use publication info" and "Reliable" checkboxes.

5)  Set appropriate on/off state and click on set. The light should respond appropriately.

 

clientcontrol.png

 

To unprovision a device from the network, long press the user button on the Eval Board. Now the provisioning process can be started afresh.

 

The base code common for all the Mesh modules are located in:

WICED-Studio-6.1\20706-A2_Bluetooth\libraries\mesh_app_lib

madhul_36

BLE MIDI Server Example

Posted by madhul_36 Jan 7, 2018

Overview

In this example, the CYW20719 device is configured as a MIDI Server that sends MIDI data over BLE. The CYW920719Q40EVB_01 Eval board is connected to a PC and keypress from the keyboard is sent as input to the PUART terminal of the CYW20719 device via Serial COM terminal interface of the Eval board. The CYW20719 maps the ASCII inputs from the PUART to MIDI notes and sends them as BLE notification to a MIDI Central in accordance with the BLE MIDI Specification.

 

Requirements

Tool: WICED Studio 6.1 and above, Any MIDI Central Client (Example: Garageband App for iOS), Serial Terminal (Example: TeraTerm, CoolTerm). This blog

Programming Language: C

Associated Parts: CYW20719

Related Hardware: CYW920719Q40EVB_01 Board

Block Diagram

middi.pngMIDI Protocol

The MIDI (Musical Instrument Digital Interface) protocol is a standard that defines the way various devices transfer music related audio data. The BLE Protocol can be used to implement the MIDI standards, enabling a connection between BLE enabled musical instruments and other devices such as Phones, computers, speakers etc., A BLE MIDI Controller should meet the following standards:

 

Scan Response Packet

  • Either the advertisement packet or scan response packet should contain the UUID of the MIDI Service in the Service UUID field. MIDI Service UUID: 03B80E5A-EDE8-4B33-A751-6CE34EC4C700
  • Below is an example for a typical scan response packet that contains the service UUID alone:

        0x11 0x07 0x00 0xC7 0xC4 0x4E 0xE3 0x6C 0x51 0xA7 0x33 0x4B 0xE8 0xED 0x5A 0x0E 0xB8 0x03 (Totally 18 Bytes)

  • First Byte 0x11 is the length (17 Bytes, excluding the length byte)
  • The second byte 0x07 indicates 128 Bit Service UUID is present.
  • The last 16 bytes are the 128 Bit UUIDs for the MIDI Service. (UUID: 03B80E5A-EDE8-4B33-A751-6CE34EC4C700)

 

GATT Database

  • The GATT Database should have a MIDI Service with UUID same as the UUID in the scan response packet (UUID: 03B80E5A-EDE8-4B33-A751-6CE34EC4C700)
  • Inside the MIDI Service, there should be a characteristic (MIDI IO Characteristic) with UUID: (7772E5DB-3868-4112-A1A9-F2669D106BF3)
  • It's properties are Read, Write without response and Notify
  • The permissions should be set to "Encryption Required"
  • The MIDI IO Characteristic should have a CCCD (Client characteristic configuration descriptor)
  • Upon pairing the MIDI Client will read the MIDI Characteristic, for which the MIDI Controller should respond with an empty packet.

 

Other Requirements

  • Connection interval < 15 mS (to avoid Jitter)
  • MTU Negotiation should be supported

 

MIDI Data Format:

The MIDI events i.e. messages are sent as notifications. The first 2 bytes of the notifications contain the time stamps in millisecond resolution.

The Byte [0] is the MIDI header. The MSB (7th Bit) is always 1 and the 6th bit is always 0. The rest of the bits contain the Most Significant 6 bits of the time stamp.

The Byte [1] is the MIDI Timestamp byte. The 7th Bit is always 1 and the rest of the 7 bits contain the lest significant 7 bits of the timestamp.

Thus the Byte [0] and the Byte[1], together contain a 13 bit time stamp in milliseconds.

The Byte [2] contain the MIDI Status (NOTE ON, NOTE OFF, Control Change, Program Change etc.,)

 

The next bytes contain the MIDI messages (Status followed by MIDI Data. Refer the MIDI Specification for more details)

 

Simple Piano Example:

This is a simple example in case of a piano. For the sake of simplicity and testing we can set the time stamps to be 0.

When the key is pressed, it is called NOTE ON message. When you release the key it is called NOTE OFF message.  NOTE ON and NOTE OFF are send as notifications. The status field of the notifications indicate whether a message is NOTE ON of NOTE OFF.

Each NOTE ON and NOTE OFF may be 5 bytes :  Byte[0], Byte[1], Byte[2, Byte[3], Byte[4]

 

Byte[0] : MIDI Header. In this example, it is always 0x80, as the timestamp is set as 0.

 

Byte[1] : Timestamp. This too will remain 0x80

 

Byte[2] :

For a NOTE ON message Byte[2] = 0x90 | Channel number

For a NOTE OFF message Byte[2] = 0x80 | Channel number

 

Channel Number:

When different musical instruments need to be played, each one  is assigned one channel number. For example, if you are using piano and drum, piano is assigned channel number 0 and drum is assigned channel number 1.

In our example, only one instrument is used. So channel number is 0.

So BYTE[2] for NOTE ON message is 0x90, Byte[2] for NOTE OFF message is 0x80

 

Byte[3]: This contains the hex code of the actual note we play.

In keyboard we have basic 12 notes. The notes and their corresponding hex codes used in this example are given in the table below:

NoteHex Code
C0x3C
C#0x3D
D0x3E
D#0x3F
E0x40
F0x41
F#0x42
G0x43
G#0x44
A0x45
A#0x46
B0x47
C10x48

 

Byte [4]: This is the velocity. This denotes how fast we press the key. It ranges from 0 to 0x7F.

If velocity is 0, it also means NOTE OFF message, even though Byte [2] is 0x90. So, for NOTE ON messages, the velocity (Byte [4]) should be a non-zero value. We usually select the middle value between 0 and 127 i.e. 63 (0x3f)

 

midipacket.png

 

Assume the following case.

 

1) User first presses C

2) Releases C

3) Presses D#

4) releases D#

 

Assuming the velocity to be 0x3F, This can be sent as 4 notifications:

 

Notification 1: 0x80 0x80 0x90 0x3c 0x3f

Notification 2: 0x80 0x80 0x80 0x3c 0x0

Notification 3: 0x80 0x80 0x90 0x3F 0x3f

Notification 4: 0x80 0x80 0x80 0x3F 0x0

 

Programming and Testing

  1. Install the WICED Studio 6.1 (or above) in your PC. Plug in two CYW920719Q40EVB_01 Boards and let the drivers bind
  2. to the devices. Make sure the jumpers are in place. Open WICED Studio and set the platform as 20719-B1_Bluetooth. For more details, please refer CYW920719Q40EVB_01-Kit-Guide.pdf present in Doc folder in the project explorer.
  3. Copy the midi_server project folder. In the WICED Studio, right-click the Apps folder in the Project Explorer pane and click Paste. You can see these folders under the Apps folder.
  4. 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.
  5. Create a Make Target for the project by selecting Project -> Make Target -> Create. Paste the following as the entry in the Target Name field:

midi_server-CYW920719Q40EVB_01 UART=COMxx download

Make sure that the Same as the Target Name checkbox is checked. Click OK.

(Note: In the above target, XX is the HCI COM Port numbers of the device.)

 

     6. Double click the Target you just created, shown in the Make Target Pane on the right. You can see the midi_server program being built and downloaded into the  board. (For more details or troubleshooting, please refer the WICED-20706-BT-Quick-Start-Guide). Once downloaded, the PUART debug logs can be seen in Teraterm.

 

   7. Have any MIDI Client and Central for connecting to the server device. The example shown here is the Garageband App for iOS. Open Garageband and go to Settings -> Bluetooth MIDI Device. The advertising MIDI Server will be shown on the device with the name “MIDI”

 

  8.Tap on the device to initiate connection and pairing. Once the pairing is completed, the instrument (Keyboard or Guitar) can be selected in the Garageband App. Now, the user can make send MIDI notes to the phone by pressing keys on the computer’s keyboard via the Serial Terminal. The below picture shows the mapping of notes with the keys in the keyboard.

 

kb.gif

 

  9. As the keys are being pressed, corresponding sound heard from the phone.

 

10. If MIDI Timestamps need to be used, enable #define USE_TIMESTAMPS macro in midi_server.h

 

11. In order to initiate disconnection from the device side, press the user button on the Eval board.

 

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-22816

CYW920719Q40EVB-01 Evaluation Board User Guide

The  User Guide can be accessed in the WICED Studio from Project Explorer -> 20719-B1_Bluetooth -> Doc

002-19103

Developing Custom Applications with BT Designer - Document

This document can be accessed from Project Explorer -> 20719-B1_Bluetooth -> Doc

Filter Blog

By date:
By tag: