UARTService.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __BLE_UART_SERVICE_H__
00018 #define __BLE_UART_SERVICE_H__
00019 
00020 #ifdef YOTTA_CFG_MBED_OS
00021 #include "mbed-drivers/mbed.h"
00022 #include "mbed-drivers/Stream.h"
00023 #else
00024 #include "Stream.h"
00025 #endif
00026 
00027 #include "ble/UUID.h "
00028 #include "ble/BLE.h"
00029 #include "ble/pal/Deprecated.h"
00030 
00031 #if BLE_FEATURE_GATT_SERVER
00032 
00033 BLE_DEPRECATED_API_USE_BEGIN()
00034 
00035 extern const uint8_t  UARTServiceBaseUUID[UUID::LENGTH_OF_LONG_UUID];
00036 extern const uint16_t UARTServiceShortUUID;
00037 extern const uint16_t UARTServiceTXCharacteristicShortUUID;
00038 extern const uint16_t UARTServiceRXCharacteristicShortUUID;
00039 
00040 extern const uint8_t  UARTServiceUUID[UUID::LENGTH_OF_LONG_UUID];
00041 extern const uint8_t  UARTServiceUUID_reversed[UUID::LENGTH_OF_LONG_UUID];
00042 
00043 extern const uint8_t  UARTServiceTXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID];
00044 extern const uint8_t  UARTServiceRXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID];
00045 
00046 /**
00047  * @class UARTService.
00048  * @brief BLE Service to enable UART over BLE.
00049  *
00050  * @deprecated This service is deprecated, and no replacement is currently available.
00051  */
00052 MBED_DEPRECATED_SINCE (
00053     "mbed-os-5.13",
00054     "This service is deprecated, and no replacement is currently available."
00055 )
00056 class UARTService {
00057 public:
00058     /** Maximum length of data (in bytes) that the UART service module can transmit to the peer. */
00059     static const unsigned BLE_UART_SERVICE_MAX_DATA_LEN = (BLE_GATT_MTU_SIZE_DEFAULT - 3);
00060 
00061 public:
00062 
00063     /**
00064     * @param _ble
00065     *               BLE object for the underlying controller.
00066     */
00067     UARTService(BLE &_ble) :
00068         ble(_ble),
00069         receiveBuffer(),
00070         sendBuffer(),
00071         sendBufferIndex(0),
00072         numBytesReceived(0),
00073         receiveBufferIndex(0),
00074         txCharacteristic(UARTServiceTXCharacteristicUUID, receiveBuffer, 1, BLE_UART_SERVICE_MAX_DATA_LEN,
00075                          GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE),
00076         rxCharacteristic(UARTServiceRXCharacteristicUUID, sendBuffer, 1, BLE_UART_SERVICE_MAX_DATA_LEN, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY) {
00077         GattCharacteristic *charTable[] = {&txCharacteristic, &rxCharacteristic};
00078         GattService         uartService(UARTServiceUUID, charTable, sizeof(charTable) / sizeof(GattCharacteristic *));
00079 
00080         ble.addService(uartService);
00081         ble.onDataWritten(this, &UARTService::onDataWritten);
00082     }
00083 
00084     /**
00085      * Note: TX and RX characteristics are to be interpreted from the viewpoint of the GATT client using this service.
00086      */
00087     uint16_t getTXCharacteristicHandle() {
00088         return txCharacteristic.getValueAttribute().getHandle();
00089     }
00090 
00091     /**
00092      * Note: TX and RX characteristics are to be interpreted from the viewpoint of the GATT client using this service.
00093      */
00094     uint16_t getRXCharacteristicHandle() {
00095         return rxCharacteristic.getValueAttribute().getHandle();
00096     }
00097 
00098     /**
00099      * We attempt to collect bytes before pushing them to the UART RX
00100      * characteristic; writing to the RX characteristic then generates
00101      * notifications for the client. Updates made in quick succession to a
00102      * notification-generating characteristic result in data being buffered
00103      * in the Bluetooth stack as notifications are sent out. The stack has
00104      * its limits for this buffering - typically a small number under 10.
00105      * Collecting data into the sendBuffer buffer helps mitigate the rate of
00106      * updates. But we shouldn't buffer a large amount of data before updating
00107      * the characteristic, otherwise the client needs to turn around and make
00108      * a long read request; this is because notifications include only the first
00109      * 20 bytes of the updated data.
00110      *
00111      * @param  _buffer The received update.
00112      * @param  length Number of characters to be appended.
00113      * @return        Number of characters appended to the rxCharacteristic.
00114      */
00115     size_t write(const void *_buffer, size_t length) {
00116         size_t         origLength = length;
00117         const uint8_t *buffer     = static_cast<const uint8_t *>(_buffer);
00118 
00119         if (ble.getGapState().connected) {
00120             unsigned bufferIndex = 0;
00121             while (length) {
00122                 unsigned bytesRemainingInSendBuffer = BLE_UART_SERVICE_MAX_DATA_LEN - sendBufferIndex;
00123                 unsigned bytesToCopy                = (length < bytesRemainingInSendBuffer) ? length : bytesRemainingInSendBuffer;
00124 
00125                 /* Copy bytes into sendBuffer. */
00126                 memcpy(&sendBuffer[sendBufferIndex], &buffer[bufferIndex], bytesToCopy);
00127                 length          -= bytesToCopy;
00128                 sendBufferIndex += bytesToCopy;
00129                 bufferIndex     += bytesToCopy;
00130 
00131                 /* Have we collected enough? */
00132                 if ((sendBufferIndex == BLE_UART_SERVICE_MAX_DATA_LEN) ||
00133                     // (sendBuffer[sendBufferIndex - 1] == '\r')          ||
00134                     (sendBuffer[sendBufferIndex - 1] == '\n')) {
00135                     ble.gattServer().write(getRXCharacteristicHandle(), static_cast<const uint8_t *>(sendBuffer), sendBufferIndex);
00136                     sendBufferIndex = 0;
00137                 }
00138             }
00139         }
00140 
00141         return origLength;
00142     }
00143 
00144     /**
00145      * Helper function to write out strings.
00146      * @param  str The received string.
00147      * @return     Number of characters appended to the rxCharacteristic.
00148      */
00149     size_t writeString(const char *str) {
00150         return write(str, strlen(str));
00151     }
00152 
00153     /**
00154      * Flush sendBuffer, i.e., forcefully write its contents to the UART RX
00155      * characteristic even if the buffer is not full.
00156      */
00157     void flush() {
00158         if (ble.getGapState().connected) {
00159             if (sendBufferIndex != 0) {
00160                 ble.gattServer().write(getRXCharacteristicHandle(), static_cast<const uint8_t *>(sendBuffer), sendBufferIndex);
00161                 sendBufferIndex = 0;
00162             }
00163         }
00164     }
00165 
00166     /**
00167      * Override for Stream::_putc().
00168      * @param  c
00169      *         This function writes the character c, cast to an unsigned char, to stream.
00170      * @return
00171      *     The character written as an unsigned char cast to an int or EOF on error.
00172      */
00173     int _putc(int c) {
00174         return (write(&c, 1) == 1) ? 1 : EOF;
00175     }
00176 
00177     /**
00178      * Override for Stream::_getc().
00179      * @return
00180      *     The character read.
00181      */
00182     int _getc() {
00183         if (receiveBufferIndex == numBytesReceived) {
00184             return EOF;
00185         }
00186 
00187         return receiveBuffer[receiveBufferIndex++];
00188     }
00189 
00190 protected:
00191     /**
00192      * This callback allows the UART service to receive updates to the
00193      * txCharacteristic. The application should forward the call to this
00194      * function from the global onDataWritten() callback handler; if that's
00195      * not used, this method can be used as a callback directly.
00196      */
00197     void onDataWritten(const GattWriteCallbackParams *params) {
00198         if (params->handle == getTXCharacteristicHandle()) {
00199             uint16_t bytesRead = params->len;
00200             if (bytesRead <= BLE_UART_SERVICE_MAX_DATA_LEN) {
00201                 numBytesReceived   = bytesRead;
00202                 receiveBufferIndex = 0;
00203                 memcpy(receiveBuffer, params->data, numBytesReceived);
00204             }
00205         }
00206     }
00207 
00208 protected:
00209     BLE                &ble;
00210 
00211     uint8_t             receiveBuffer[BLE_UART_SERVICE_MAX_DATA_LEN]; /**< The local buffer into which we receive
00212                                                                        *   inbound data before forwarding it to the
00213                                                                        *   application. */
00214 
00215     uint8_t             sendBuffer[BLE_UART_SERVICE_MAX_DATA_LEN];    /**< The local buffer into which outbound data is
00216                                                                        *   accumulated before being pushed to the
00217                                                                        *   rxCharacteristic. */
00218     uint8_t             sendBufferIndex;
00219     uint8_t             numBytesReceived;
00220     uint8_t             receiveBufferIndex;
00221 
00222     GattCharacteristic  txCharacteristic; /**< From the point of view of the external client, this is the characteristic
00223                                            *   they'd write into in order to communicate with this application. */
00224     GattCharacteristic  rxCharacteristic; /**< From the point of view of the external client, this is the characteristic
00225                                            *   they'd read from in order to receive the bytes transmitted by this
00226                                            *   application. */
00227 };
00228 
00229 BLE_DEPRECATED_API_USE_END()
00230 
00231 #endif // BLE_FEATURE_GATT_SERVER
00232 
00233 #endif /* #ifndef __BLE_UART_SERVICE_H__*/