Peripheral Device with UART Server Sample Code ============================================== NOTE: If you use this sample application for your own purposes, follow the licensing agreement specified in Software_Use_Agreement.rtf in the home directory of the installed RSL10 Evaluation and Development Kit (EDK). Overview -------- This sample project generates a battery service, a custom service, and a UART interface with a baud rate of 115200. It then starts an undirected connectable advertising with the device's public address, if an address is available at DEVICE_INFO_BLUETOOTH_ADDR in non-volatile memory three (NVR3). If this address is not defined (all 1s or 0s), use a pre-defined, private Bluetooth(R) address (PRIVATE_BDADDR) located in ble_std.h. For this sample project, any central device can scan, connect, and perform service discovery, receive battery value notifications, or read the battery value. The central device has the ability to read and write custom attributes. The RSL10 ADC is used to read the battery level value every 200 ms when there is a kernel timer event. The average for 16 reads is calculated, and if this average value changes, a flag is set to send a battery level notification. In addition, if the custom service notification is enabled, it sends a notification with an incremental value every six seconds. This sample project passes through several states before all services are enabled: 1. APPM_INIT (initialization) Application initializing and is configured into an idle state. 2. APPM_CREATE_DB (create database) Application has configured the Bluetooth stack, including GAP, according to the required role and features. It is now adding services, handlers, and characteristics for all services that it will provide. 3. APPM_READY (ready) Application has added the desired standard and custom services or profiles into the Bluetooth GATT database and handlers. 4. APPM_ADVERTISING (advertising) The device starts advertising based on the sample project. 5. APPM_CONNECTED (connected) Connection is now established with another compatible device. After establishing connection, the BLE_SetServiceState function is called, in which, for any profiles/services that need to be enabled, an enable request message is sent to the corresponding profile of the Bluetooth stack. Once the response is received for the specific profile, a flag is set to indicate to the application that it is enabled and ready to use. Next, the UART exchange is initiated. The UART data is buffered for TX and RX using two DMA buffers. The UART RX DMA buffer is periodically polled for data that has been received, and if data is available, this is sent out in BLE packets. Conversely if data has been received from the Bluetooth custom service, it is added to the UART TX DMA buffer for output. NOTE: The DMA is used without interrupts, in order to demonstrate support for an arbitrary-length data transfer without the need for handling each individual received word from the specified interface. This application uses the following optional features of Bluetooth low energy technology when the connected device also supports them: - LE 2M PHY (Bluetooth 5): Use of this feature allows the device to transfer data using a symbol rate/bit rate of 2 Mb/s, reducing the amount of time that the radio is active (reducing power), and allows for the possibility of higher throughput transfers. - LE Data Packet Length Extension (Bluetooth 4.2): Use of this feature allows this application to request an increase in the maximum transfer unit (MTU) allowed. This feature supports a maximum increase in the underlying data packet size from 27 bytes to 251 bytes, and this application supports a maxiumum packet size of 250 bytes per packet. Structure --------- This sample project is structured as follows: The source code exists in a "code" folder, all application-related include header files are in the "include" folder, and the main() function "app.c" is located in the parent directory. Code ---- app_init.c - All initialization functions are called here, but the implementation is in the respective C files app_process.c - Message handlers for the application ble_bass.c - Support functions and message handlers pertaining to the Battery Service Server ble_custom.c - Support functions and message handlers pertaining to the Custom Service Server ble_std.c - Support functions and message handlers pertaining to Bluetooth low energy technology uart.c - Support code for handling DMA-based UART data transfers Include ------- app.h - Overall application header file ble_bass.h - Header file for the Battery Service Server ble_custom.h - Header file for the Custom Service Server ble_std.h - Header file for the Bluetooth low energy standard uart.h - Header file for the DMA-based UART data tranfer support code Hardware Requirements --------------------- This application can be executed on any Evaluation and Development Board. The application needs to be connected to a terminal application or similar that can read and write serial UART data at 115200 baud. For a QFN-based RSL10 Evaluation and Development Board, no external connections are required. For a WLCSP-based RSL10 Evaluation and Development Board, connect: - P4:TX0 to DIO4 - P4:RX0 to DIO5 Importing a Project ------------------- To import the sample code into your IDE workspace, refer to the Getting Started Guide for your IDE for more information. Select the project configuration according to the chip ID version of RSL10. The appropriate libraries and include files are loaded according to the build configuration that you choose. Use "Debug" for CID 101. Ensure that the device CID matches the application build. Verification ------------ To verify the BLE functionality, use RSL10 or another third-party central device application to establish a connection. In addition to establishing a connection, this application can be used to read/write characteristics and receive notifications. To show how an application can send notifications, for every 30 timer expirations a notification request flag is set, and the application sends an incremental value of the first attribute to a peer device. Alternatively, while the Bluetooth application manager is in the state "APPM_ADVERTISING", the LED on the Evaluation and Development Board (DIO6) is blinking. It turns on steadily once the link is established, and it enters the APPM_CONNECTED state. The UART functionality can be verified by connecting a terminal application to RSL10 to send and receive serial data at the specified baud rate. The correct COM ports to use can be identified using the computer's Device Manager. Look for "JLink CDC UART Port (COMxx)". Once connected, character strokes written to the terminal of central_client_uart are echoed back to the terminal of peripheral_server_uart. Similarly, character strokes written to the terminal of peripheral_server_uart are echoed back to the terminal of central_client_uart. Note that some terminal programs don't handle carriage return characters cleanly, and will restart progress on a line following a carriage return without inserting a newline. Notes ----- #1 The theoretical maximum throughput for a Bluetooth low energy connection is 175 kB per second (if sending data in only one direction), and lower if sending bi-directional traffic. This application attempts to maximize the effective throughput for both single direction and bi-directional transfers, and implements buffering of the incoming UART data to ensure that we don’t lose data if we exceed the effective throughput for a short period of time. For larger files at high data rates (beyond 115,200 baud), or a pair of files being transferred bi-directionally at moderate data rates (beyond 25,000 baud), this can overflow the internal buffers and cause packet loss. A user could extend the UART application to implement UART traffic flow control to ensure that buffer overflows do not occur. #2 Sometimes the firmware in RSL10 cannot be successfully re-flashed, due to the application going into Sleep Mode or resetting continuously (either by design or due to programming error). To circumvent this scenario, a software recovery mode using DIO12 can be implemented with the following steps: 1. Connect DIO12 to ground. 2. Press the RESET button (this restarts the application, which will pause at the start of its initialization routine). 3. Re-flash RSL10. After successful re-flashing, disconnect DIO12 from ground, and press the RESET button so that the application will work properly. ============================================================================== Copyright (c) 2017 Semiconductor Components Industries, LLC (d/b/a ON Semiconductor).