|
| 1 | + |
| 2 | +Purpose / Scope |
| 3 | +=============== |
| 4 | + |
| 5 | +This purpose of this example is to demonstrate a simple serial socket using |
| 6 | +TI's Simple Stream Server profile. The example showcases a simple UART over |
| 7 | +BLE implementation. The project is designed to allow the actual data sink and |
| 8 | +source to be easily exchanged for the purpose of creating a generic simple |
| 9 | +stream application. |
| 10 | + |
| 11 | +Prerequisites |
| 12 | +============= |
| 13 | + |
| 14 | +#### Hardware Requirements |
| 15 | + |
| 16 | +Before running the demo, the user will need the following components: |
| 17 | + |
| 18 | +- 2x [CC2640R2 Launchpad](http://www.ti.com/tool/LAUNCHXL-CC2640R2) |
| 19 | +- 2x Micro USB cable |
| 20 | + |
| 21 | +#### Firmware Requirements |
| 22 | + |
| 23 | +- [CC2640R2 SDK](http://www.ti.com/tool/SIMPLELINK-CC2640R2-SDK) |
| 24 | + |
| 25 | +Simple Stream Server Service |
| 26 | +============================ |
| 27 | + |
| 28 | +The simple stream service is made to implement a bi-directional data stream |
| 29 | +connection over the BLE protocol. The service uses a 128 bit UUID: |
| 30 | +F000C0C0-0451-4000-B000-00000000-0000. simple stream server service contains |
| 31 | +two characteristics, they are listed below. |
| 32 | + |
| 33 | +| Characteristic | UUID | |
| 34 | +|:-----------------:|:-----------------------------------------:| |
| 35 | +|DataIn | F000C0C1-0451-4000-B000-00000000-0000 | |
| 36 | +|DataOut | F000C0C2-0451-4000-B000-00000000-0000 | |
| 37 | + |
| 38 | +The `DataIn` characteristic implies data coming from client to server while |
| 39 | +`DataOut` is data outgoing from server to client. |
| 40 | + |
| 41 | +For more information on the service, see the Simple Serial Socket Server example readme. |
| 42 | + |
| 43 | +Simple Stream Client Profile |
| 44 | +============================ |
| 45 | + |
| 46 | +The simple stream client profile provides an easy to use interface for |
| 47 | +interaction with a connected Simple Stream Server peripheral. The simple stream |
| 48 | +client profile is similar to the simple stream server service. Following a |
| 49 | +connection, the service table provided by the profile has to be populated with |
| 50 | +service handles before any data can be sent from the client to the server. |
| 51 | + |
| 52 | +The service table can be easily populated by utilizing the simple service |
| 53 | +discovery API available in the example. To see how this API is used during the |
| 54 | +discovery process, refer to the `SimpleSerialSocketClient_processGATTDiscEvent` |
| 55 | +function found inside `simple_serial_socket_client`. |
| 56 | + |
| 57 | +The profile provided APIs: |
| 58 | +\* SimpleStreamClient_sendData(uint16_t connHandle, void *data, uint16_t len) |
| 59 | +\* SimpleStreamClient_processStream() |
| 60 | +\* SimpleStreamClient_disconnectStream() |
| 61 | +\* SimpleStreamClient_enableNotifications(uint16_t connHandle) |
| 62 | + |
| 63 | +The Simple Serial Client keeps an internal FIFO list for data sent to the |
| 64 | +profile using `SimpleStreamClient_sendData()`. When new data is sent to the |
| 65 | +profile, the internal queue will be processed and as much data as possible |
| 66 | +will be sent to the server using write commands (no-respond). |
| 67 | + |
| 68 | +> Note: The Simple Serial Client profile relies on dynamic memory allocated and |
| 69 | +> will use the application ICall heap to store the queued data. |
| 70 | +
|
| 71 | +If the profile is unable to send all data inside the current connection event, |
| 72 | +`SimpleStreamClient_processStream()` can be called in application space to |
| 73 | +process the internal queue again at another time. |
| 74 | + |
| 75 | +If the client disconnects from the server, the internal queue can be flushed |
| 76 | +by calling `SimpleStreamClient_disconnectStream()`. |
| 77 | + |
| 78 | +To receive incoming data, the client has to enable notifications. To do this, |
| 79 | +the `SimpleStreamClient_enableNotifications()` API can be used to enable |
| 80 | +notifications given the connection handle. |
| 81 | + |
| 82 | +Running the Demo |
| 83 | +================ |
| 84 | + |
| 85 | +Running the demo is as simple and compiling and loading the code, then hooking |
| 86 | +up to your PC to send a receive data over UART. Please see the steps below: |
| 87 | + |
| 88 | +1. Compile and load the code |
| 89 | + - Build and load LaunchPad #1 with the `simple_serial_socket_client` project |
| 90 | + - Build and load LaunchPad #2 with the `simple_serial_socket_server` project |
| 91 | + |
| 92 | +2. Connect the boards to the PC terminal |
| 93 | + - You can use the terminal to send data from your PC to the LaunchPad, and |
| 94 | + also display the info sent from one device to another. |
| 95 | + - You will need to open two instances of the terminal program, one to |
| 96 | + communicate with each board. |
| 97 | + - Follow the steps from our [FAQ](faq.md) to connect to the LaunchPad boards |
| 98 | + - **Please note that the Simple Serial Socket project uses the default baud |
| 99 | + rate of 115200** |
| 100 | + |
| 101 | +3. Power the boards individually and verify they are initialized |
| 102 | + - The client will auto connect to the server by looking for an advertisement |
| 103 | + containing the SSS service together with a matching manufacturer ID. The |
| 104 | + manufacturer ID can be changed in both projects to allow for multiple |
| 105 | + devices to run alongside each other. |
| 106 | + - Upon connecting the client and server will light the red LED. When |
| 107 | + notifications has been enabled and the stream is ready for use, the green |
| 108 | + LED will also be lit. |
| 109 | + - At this point you can type into either terminal window and watch it being |
| 110 | + echoed to the other terminal via BLE. The example has been tested using |
| 111 | + PuTTY and CCS's terminal. |
| 112 | + |
| 113 | +  |
| 114 | + |
| 115 | +4. Trouble shooting: |
| 116 | + - Verify that the RXD and TXD jumpers of each boosterpack are set correctly |
| 117 | + - Try using a different terminal |
| 118 | + - Verify you are using the right serial ports (see [FAQ](faq.md)) |
| 119 | + - Try not using an USB hub |
| 120 | + |
| 121 | +Improving UART performance for large data transfers |
| 122 | +=================================================== |
| 123 | + |
| 124 | +#### Buffers size |
| 125 | + |
| 126 | +The default board file configures the size of the internal UART ring buffer to |
| 127 | +32 bytes. If the amount of data sent over UART to the device exceeds |
| 128 | +UART_MAX_READ_SIZE plus the size of the ring buffer, data loss is probable. |
| 129 | +This is due to the internal UART ring buffer wrapping before the application |
| 130 | +has the chance to process the previous UART buffer. To be able to handle |
| 131 | +larger chunks of data, the size of the ring buffer can be increased inside the |
| 132 | +board file. |
| 133 | + |
| 134 | +In order to modify the size of the board file, the `board.c` file found inside |
| 135 | +the `Startup` folder need to be replaced with copies of the actual board |
| 136 | +files. This can be done by performing the following steps: |
| 137 | + |
| 138 | +- Remove the `board.c` file found inside the `Startup` folder. |
| 139 | +- Copy the following files from `<SDK DIR>/source/ti/ble5stack/boards/CC2640R2_LAUNCHXL` directory into the projects `Startup` folder: |
| 140 | + - Board.h |
| 141 | + - CC2640R2_LAUNCHXL.h |
| 142 | + - CC2640R2_LAUNCHXL.c |
| 143 | + - CC2640R2_LAUNCHXL_fxns.c |
| 144 | + |
| 145 | +The ring buffer size can now be changed by resizing the uartCC26XXRingBuffer |
| 146 | +array found inside `CC2640R2_LAUNCHXL.c`. |
| 147 | + |
| 148 | +It is also possible to modify the shared `CC2640R2_LAUNCHXL.c` file that |
| 149 | +`board.c` imports directly instead of coping the board files into the project. |
| 150 | +This is however not recommended as changes will propagate to all BLE examples in the SDK |
| 151 | +that depend on the shared file. |
| 152 | + |
| 153 | +#### Baud rate |
| 154 | +As written before, the default baud rate is set to 115200. This value can be |
| 155 | +modified by changing the UART parameters, especially `uartParams.baudRate`. |
| 156 | +The reader’s attention is drawn to the fact that changing the baud rate is |
| 157 | +not the recommended way of increasing throughput. In most of the cases, the |
| 158 | +throughput is actually limited by the BLE throughput. |
0 commit comments