4.1.2.4 Bluetooth®LE Transparent UART

This section helps users to create a peripheral device and send/receive characters between two connected Bluetooth LE devices over Microchip proprietary Transparent UART Profile. Peripheral device will be the PIC32WM-BW1 Curiosity board and central device can either be a Smart phone with Light Blue app or another PIC32WM-BW1 Curiosity board.

Users can choose to run the precompiled application example .hex file on the PIC32WM-BW1 Curiosity board and experience the demo or go through the steps involved in developing this application from scratch.

Hardware Requirement

Table 4-12. Hardware Requirement
Tool Qty
PIC32WM-BW1 Curiosity Board1
Micro USB cable1
USB Type-C™ Smart phone1

Software Requirement

  • To install Tera Term tool, refer to the Tera Term web page listed in the Reference Documentation from Related Links.

Smart phone App

  • Light Blue iOS/Android app available in stores

Programming the Precompiled Hex File or Application Example

Programming the .hex File using MPLAB X IPE

  1. Import and program the precompiled .hex file is located in “<Harmony Content Path>\wireless_apps_pic32_bw1\apps\ble\peripheral\peripheral_trp_uart\hex” folder
  2. For detailed steps, refer to Programming a Device in MPLAB® IPE in Reference Documentation from Related Links.
    Note: Ensure to choose the correct Device and Tool information.

Programming the Application using MPLAB X IDE

  1. Perform the following the steps mentioned in Running a Precompiled Example. For more information, refer to Running a Precompiled Application Example from Related Links.
  2. Open and program the application example “peripheral_trp_uart.X” located in “<Harmony Content Path>\wireless_apps_pic32_bw1\apps\ble\peripheral\peripheral_trp_uart\firmware” using MPLAB X IDE

Testing

  1. The application enables users to exchange data back and forth over UART between two BLE connected devices
  2. Program PIC32WM-BW1 Curiosity Board with “peripheral_trp_uart” application and open Tera Term configured at following settings through Terminal Settings:
    Terminal Settings
    • Baud Rate/Speed – 115200
    • Parity – None
    • Data Bits – 8
    • Stop Bits – 1
    • Flow Control – None
  3. Reset the board. Upon Reset, “BW1-Advertising” is displayed on the Tera Term.
  4. Launch the Light Blue mobile app and search for the device name “pic32wm-bw1” and press Connect. When the connection is established, the user will see “Connected” on Tera Term.
    Figure 4-77. LightBlue® App
  5. To send data from the PIC32WM-BW1 Curiosity Board (peripheral device) to the mobile app (central device), select “UUID: 49535343-1E4D-4BD9-BA61-23C647249616” then select Subscribe.
  6. Change the data format to UTF-8 String in the Light Blue mobile app by clicking on Hex at the left top corner.
  7. Type characters on Tera Term emulator and the received data can be seen on the app under Notified values. For example, in the above figure we see that when we send : “234” we see that on the app.
    Figure 4-78. Tera Term Logs
  8. To send data to the PIC32WM-BW1 Curiosity Board (peripheral device) from the mobile app (central device), select “UUID: 49535343-8841-43F4-A8D4-ECBE34729BB3”. Change the data format to UTF-8 String as before.
    Note: When connecting through the LightBlue® app on Android, select the following properties: Write and Write Without Response.
  9. Type a message like “Hi! Test” on the app and see it appearing on the Tera Term.
    Figure 4-79. LightBlue® App
  10. Users can use another PIC32WM-BW1 Curiosity Board configured as BLE Central Transparent UART instead of using a mobile app.

Project Graph

This section explains how MCC Project graph must look like and component configurations.
  1. Verify if the Project Graph window has all the expected configuration as illustrated in the following figure.
Note: Ensure that the macro configUSE_TICKLESS_IDLE is set to 0. The macro is available in FreeRTOSConfig.h file.
#define configUSE_TICKLESS_IDLE 0
Figure 4-80. Project Graph

Verifying Advertisement,Connection and Transparent UART Profile Configuration

  1. Select BLE Stack component in project graph, to open component configuration and configure as illustrated in the following figure.

    Figure 4-81. BLE Stack Configuration
  2. Select Transparent Profile component in project graph, to open component configuration and configure as illustrated in the following figure.
    Figure 4-82. Transparent Profile Configuration

Generating a Code

For more details on code generation, refer to MPLAB Code Configurator (MCC) Code Generation from Related Links.

Files and Routines Automatically Generated by the MCC

After generating the program source from the MCC interface by clicking Generate Code, the BLE configuration source and header files can be found in the following project directories.
Figure 4-83. Project File
The OSAL, RF System, and BLE System initialization routine executed during program initialization can be found in the following project file. This initialization routine is automatically generated by the MCC.
Figure 4-84. initialization.c

The BLE stack initialization routine executed during application initialization can be found in project files. This initialization routine is automatically generated by the MCC. This call initializes and configures the GAP, GATT, SMP, L2CAP and BLE middleware layers.

Here are also the auto generated Advertisement Data (AD) structures and types as reference.
Figure 4-85. AD Structures and Types
Table 4-13. Source Files
Source Files Usage
app.cApplication State machine, includes calls for Initialization of all BLE stack (GAP,GATT, SMP, L2CAP) related component configurations
app_ble\app_ble.cSource Code for the BLE stack related component configurations, code related to function calls from app.c
app_ble\app_ble_handler.cAll GAP, GATT, SMP and L2CAP Event handlers
app_ble\app_trsps_handler.cAll Transparent UART Server related Event handlers
ble_trsps.cAll Transparent Server Functions for user application
Note: app.c is auto generated and has a state machine based application code. Users can use this template to develop their own application.

Header Files

  • ble_gap.h: Contains BLE GAP functions and is automatically included in the app.c file.

  • ble_trsps.h: is associated with APIs and structures related to BLE Transparent Client functions for application user.

Function Calls

  • MCC generates and adds the code to initialize the BLE Stack GAP, GATT, SMP and L2CAP in APP_BleStackInit() function.
  • APP_BleStackInit() is the API that will be called inside the Applications Initial State (APP_STATE_INIT) in app.c.

User Application Development

  1. Include:
    1. Include the user action. For more information, refer to User Action from Related Links.
    2. ble_trsps.h in app.c, BLE Transparent UART Server related APIs.
    3. osal/osal_freertos_extend.h in app_trsps_handler.c, OSAL related APIs are available here.
    4. definitions.h must be included in all the files where UART will be used to print debug information.
      Note: definitions.h is not specific to just UART but instead must be included in all the application source files where any peripheral functionality will be exercised.
  2. Set Public Device Address in app_ble.c in APP_BleConfigBasic()
    BLE_GAP_Addr_T devAddr;
devAddr.addrType = BLE_GAP_ADDR_TYPE_PUBLIC;
devAddr.addr[5] = 0xC6;
devAddr.addr[4] = 0xC5;
devAddr.addr[3] = 0xC4;
devAddr.addr[2] = 0xC3;
devAddr.addr[1] = 0xC2;
devAddr.addr[0] = 0xC1;
// Configure device address
BLE_GAP_SetDeviceAddr(&devAddr);
    Figure 4-86. app_ble.c
  3. Starting Advertisement in app.c, APP_Tasks() case APP_STATE_INIT
    // Enable UART Read
SERCOM0_USART_ReadNotificationEnable(true, true);
// Set UART RX notification threshold to be 1
SERCOM0_USART_ReadThresholdSet(1);
// Register the UART RX callback function
SERCOM0_USART_ReadCallbackRegister(uart_cb, (uintptr_t)NULL);
// Start Advertisement
BLE_GAP_SetAdvEnable(0x01, 0x00);
SERCOM0_USART_Write((uint8_t *)"BW1-Advertising\r\n",17);
    Figure 4-87. app.c
  4. Connected and Disconnected Events in app_ble_handler.c
    1. Connection handle associated with the peer peripheral device needs to be saved for data exchange after a BLE connection

    2. p_event->eventField.evtConnect.connHandle has this information

      #include "peripheral/sercom/usart/plib_sercom0_usart.h"
extern uint16_t conn_hdl;
    3. In APP_BleGapEvtHandler(), case BLE_GAP_EVT_CONNECTED:
      /* TODO: implement your application code.*/
SERCOM0_USART_Write((uint8_t *)"Connected\r\n",11);
conn_hdl = p_event->eventField.evtConnect.connHandle;

    4. In APP_BleGapEvtHandler(), case BLE_GAP_EVT_DISCONNECTED:

      /* TODO: implement your application code.*/
SERCOM0_USART_Write((uint8_t *)"Disconnected\r\n",14);
    Figure 4-88. app_ble_handler.c
  5. Transmit Data:
    1. Add APP_MSG_UART_CB to APP_MsgId_T enum in app.h
      Figure 4-89. app.h
    2. BLE_TRSPS_SendData(conn_hdl , 1, &data); is the API to be used for sending data to the central device.
    3. Example for transmitting over UART using the BLE_TRSPS_SendData() API in app.c
      #include "ble_trsps/ble_trsps.h"
uint16_t conn_hdl;// connection handle info captured @BLE_GAP_EVT_CONNECTED event
uint16_t ret;
uint8_t uart_data;
void uart_cb(SERCOM_USART_EVENT event, uintptr_t context)
{
    APP_Msg_T appMsg;
    // If RX data from UART reached threshold (previously set to 1)
    if( event == SERCOM_USART_EVENT_READ_THRESHOLD_REACHED )
   {
     // Read 1 byte data from UART
     SERCOM0_USART_Read(&uart_data, 1);
     appMsg.msgId = APP_MSG_UART_CB;  
     OSAL_QUEUE_Send(&appData.appQueue, &appMsg, 0);
    }
}
void APP_UartCBHandler()
{
// Send the data from UART to connected device through Transparent service
    BLE_TRSPS_SendData(conn_hdl, 1, &uart_data);
}
    4. In APP_Tasks(), case APP_STATE_SERVICE_TASKS:
      else if(p_appMsg->msgId==APP_MSG_UART_CB)
{
// Pass BLE UART Data transmission target BLE UART Device handling
     APP_UartCBHandler();
}
      Figure 4-90. app.c
  6. Receive Data
    1. BLE_TRSPS_EVT_RECEIVE_DATA is the event generated when data is sent from the central device
    2. Use the BLE_TRSPS_GetDataLength(p_event->eventField.onReceiveData.connHandle, &data_len); API to extract the length of the application data received
    3. BLE_TRSPS_GetData(p_event->eventField.onReceiveData.connHandle, data); API is used to retrieve the data
      Note: BLE_TRSPS_Event_T p_event structure stores the information about BLE transparent UART callback functions.
    4. Example for printing the received data from the central device over UART in app_trsps_handler.c
      #include <string.h>
#include "stdint.h"
#include "ble_trsps/ble_trsps.h"
#include "osal/osal_freertos_extend.h"
#include "definitions.h"
    5. In APP_TrspsEvtHandler(), case BLE_TRSPS_EVT_RECEIVE_DATA:
      /* TODO: implement your application code.*/
uint16_t data_len;
uint8_t *data;
// Retrieve received data length
BLE_TRSPS_GetDataLength(p_event->eventField.onReceiveData.connHandle, &data_len);
// Allocate memory according to data length
data = OSAL_Malloc(data_len);
if(data == NULL)
      break;
// Retrieve received data
BLE_TRSPS_GetData(p_event->eventField.onReceiveData.connHandle, data);
// Output received data to UART
SERCOM0_USART_Write(data, data_len);
// Free memory
OSAL_Free(data);
      Figure 4-91. app_trsps_handler.c