5.1.2.6 BLE Transparent UART

Recommended Readings

1. Getting Started with Application Building Blocks – See Building Block Examples from Related Links.

2. Getting Started with Peripheral Building Blocks – See Peripheral Devices from Related Links.

3. See BLE Transparent UART from Related Links.
4. See BLE Connection from Related Links

5. BLE Software Specification – See MPLAB® Harmony Wireless BLE in Reference Documentation from Related Links.

Hardware Requirement

SDK Setup

Refer to Getting Started with Software Development from Related Links.

Software Requirement

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

Smart phone App

Light Blue iOS/Android app available in stores

Programming the Precompiled Hex File or Application Example

Using MPLAB® X IPE:

1. Import and program the precompiled hex file: <Discover Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\building_blocks\Peripheral\profiles_services\peripheral_trp_uart\hex\peripheral_trp_uart.hex.
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.

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 <Discover Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\profiles_services\peripheral_trp_uart\firmware\peripheral_trp_uart.X.
3. For more details on how to find the Discover path, refer to Download Application Example from Discover in Running a Precompiled Application Example from Related Links.

Demo Description

This application enables users to send data back and forth over UART between two connected BLE devices. On Reset, demo application prints “Advertising” which denotes the start of advertisements and then “Connected” when connection is established. Application data to be sent to the connected central device (smart phone or another WBZ351 Curiosity board) is entered in a terminal emulator like Tera Term.

Testing

1. Using a Micro USB cable, connect the Debug USB on the Curiosity board to a PC. The Active LED turns Green once connected to the PC.
2. Program the precompiled hex file or application example as mentioned.
3. Open TeraTerm and configure as mentioned below:
   Terminal Settings

   • Baud Rate/Speed – 115200 (as configured in SERCOM configuration)
   • Parity – None
   • Data Bits – 8
   • Stop Bits – 1
   • Flow Control – None

   For more details on how to set the “Serial Port” and “Speed”, refer to COM Port Setup in Running a Precompiled Application Example from Related Links.

4. Press the Reset Switch on the Curiosity board.
5. Launch the Light Blue mobile app and search for the device name “pic32cx-bz/Microchip” and press Connect.

   

6. To receive data from the WBZ351 Curiosity board (peripheral device) to the mobile app (central device), select “UUID: 49535343-1E4D-4BD9-BA61-23C647249616” then select Subscribe.

   

   

7. Change the Data format to UTF-8 String in the Light Blue mobile app then enter "test" on Tera Term. The same data must be displayed in the app.
   Note: User may not be able to see “test” on the Tera Term as user types.

   

8. To send data from the mobile app (central device) to the WBZ351 Curiosity board (peripheral device), select “UUID: 49535343-8841-43F4-A8D4-ECBE34729BB3”.

   

9. Change the Data format to UTF-8 String then enter “trp uart” and click Write. The same data must be displayed in Tera Term (see the following figure).

   

   Note: Users can use another WBZ351 Curiosity board configured as BLE Transparent UART (central) instead of using a mobile app. For more information, refer to BLE Transparent UART from Related Links.

Developing the Application from Scratch using MCC

1. Create a new harmony project. For more details, see Creating a New MCC Harmony Project from Related Links.
2. Import component configuration – This step helps users setup the basic components and configuration required to develop this application. The imported file is of format .mc4 and is located in the path <Discover Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\profiles_services\peripheral_trp_uart\firmware\peripheral_trp_uart.X. For more details on importing the component configuration, refer to Importing Existing App Example Configuration from Related Links.
   Note: Import and export functionality of Harmony component configuration will help users to start from a known working setup of MCC configuration.
3. Accept dependencies or satisfiers when prompted.
4. Verify if the project graph window has all the expected configuration.
   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

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.

   

   Note: If users cannot see the Configuration Options panel in the right-hand side of the MPLAB X IDE, it might be minimized. Hover the cursor towards the Configuration Options side tab and click the “dot” on the top right-hand corner to pin it (see the following figure).

   

   .
2. Select Transparent Profile component in project graph, to open component configuration and configure as illustrated in the following figure.

   

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.

Initialization routines for OSAL, RF System, and BLE System are auto-generated by the MCC. See OSAL Libraries Help in Reference Documentation from Related Links. Initialization routine executed during program initialization can be found in the project files.

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.

Autogenerated, Advertisement Data Format

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

Include

• Include the user action. For more information, refer to User Action from Related Links.
• ble_trsps.h in app.c, BLE Transparent UART Server related APIs.
• osal/osal_freertos_extend.h in app_trsps_handler.c, OSAL related APIs are available here.
• 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.

Set Public Device Address in app_ble.c

• BLE_GAP_SetDeviceAddr(&devAddr);

    BLE_GAP_Addr_T devAddr;
    devAddr.addrType = BLE_GAP_ADDR_TYPE_PUBLIC;
    devAddr.addr[0] = 0xA1;
    devAddr.addr[1] = 0xA2;
    devAddr.addr[2] = 0xA3;
    devAddr.addr[3] = 0xA4;
    devAddr.addr[4] = 0xA5;
    devAddr.addr[5] = 0xA6;

    // Configure device address
    BLE_GAP_SetDeviceAddr(&devAddr);

Starting Advertisement

• BLE_GAP_SetAdvEnable(0x01, 0x00);

  

Connected and Disconnected Events

• In app_ble_handler.c, BLE_GAP_EVT_CONNECTED event will be generated when a BLE connection is completed

Connection Handler

• Connection handle associated with the peer peripheral device needs to be saved for data exchange after a BLE connection
• p_event->eventField.evtConnect.connHandle has this information

  

Transmit Data

• Add “APP_MSG_UART_C” to the generated APP_MsgId_T

  

• BLE_TRSPS_SendData(conn_hdl , 1, &data); is the API to be used for sending data to the central device.
  Note: The precompiled application example uses a UART callback to initiate the data transmission upon receiving a character in UART.

• Example for transmitting over UART using the BLE_TRSPS_SendData() API

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);      
}
  // Register call back when data is available on UART for Peripheral Device to send
// 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);

else if(p_appMsg->msgId==APP_MSG_BLE_STACK_LOG)
{
   // Pass BLE LOG Event Message to User Application for handling
   APP_BleStackLogHandler((BT_SYS_LogEvent_T *)p_appMsg->msgData);
}
else if(p_appMsg->msgId==APP_MSG_UART_CB)
{
   // Pass BLE UART Data transmission target BLE UART Device handling
   APP_UartCBHandler();
}

Receive Data

• BLE_TRSPS_EVT_RECEIVE_DATA is the event generated when data is sent from the central device
• Use the BLE_TRSPS_GetDataLength(p_event->eventField.onReceiveData.connHandle, &data_len); API to extract the length of the application data received
• 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.
• Example for printing the received data from the central device over UART

  /* 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);

Where to go from Here

• BLE Sensor App – This application utilizes the Transparent UART building block, see BLE Sensor with Touch from Related Links.