MicroBitUARTService.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 #ifndef MICROBIT_UART_SERVICE_H
00027 #define MICROBIT_UART_SERVICE_H
00028 
00029 #include "mbed.h"
00030 #include "ble/UUID.h"
00031 #include "ble/BLE.h"
00032 #include "MicroBitConfig.h"
00033 #include "MicroBitSerial.h"
00034 
00035 #define MICROBIT_UART_S_DEFAULT_BUF_SIZE    20
00036 
00037 #define MICROBIT_UART_S_EVT_DELIM_MATCH     1
00038 #define MICROBIT_UART_S_EVT_HEAD_MATCH      2
00039 #define MICROBIT_UART_S_EVT_RX_FULL         3
00040 
00041 /**
00042   * Class definition for the custom MicroBit UART Service.
00043   * Provides a BLE service that acts as a UART port, enabling the reception and transmission
00044   * of an arbitrary number of bytes.
00045   */
00046 class MicroBitUARTService
00047 {
00048     uint8_t* rxBuffer;
00049 
00050     uint8_t* txBuffer;
00051 
00052     uint8_t rxBufferHead;
00053     uint8_t rxBufferTail;
00054     uint8_t rxBufferSize;
00055 
00056     uint8_t txBufferSize;
00057 
00058     uint32_t rxCharacteristicHandle;
00059 
00060     // Bluetooth stack we're running on.
00061     BLEDevice           &ble;
00062 
00063     //delimeters used for matching on receive.
00064     ManagedString delimeters;
00065 
00066     //a variable used when a user calls the eventAfter() method.
00067     int rxBuffHeadMatch;
00068 
00069     /**
00070       * A callback function for whenever a Bluetooth device writes to our TX characteristic.
00071       */
00072     void onDataWritten(const GattWriteCallbackParams *params);
00073 
00074     /**
00075       * An internal method that copies values from a circular buffer to a linear buffer.
00076       *
00077       * @param circularBuff a pointer to the source circular buffer
00078       * @param circularBuffSize the size of the circular buffer
00079       * @param linearBuff a pointer to the destination linear buffer
00080       * @param tailPosition the tail position in the circular buffer you want to copy from
00081       * @param headPosition the head position in the circular buffer you want to copy to
00082       *
00083       * @note this method assumes that the linear buffer has the appropriate amount of
00084       *       memory to contain the copy operation
00085       */
00086     void circularCopy(uint8_t *circularBuff, uint8_t circularBuffSize, uint8_t *linearBuff, uint16_t tailPosition, uint16_t headPosition);
00087 
00088     public:
00089 
00090     /**
00091      * Constructor for the UARTService.
00092      * @param _ble an instance of BLEDevice
00093      * @param rxBufferSize the size of the rxBuffer
00094      * @param txBufferSize the size of the txBuffer
00095      *
00096      * @note The default size is MICROBIT_UART_S_DEFAULT_BUF_SIZE (20 bytes).
00097      */
00098     MicroBitUARTService(BLEDevice &_ble, uint8_t rxBufferSize = MICROBIT_UART_S_DEFAULT_BUF_SIZE, uint8_t txBufferSize = MICROBIT_UART_S_DEFAULT_BUF_SIZE);
00099 
00100     /**
00101       * Retreives a single character from our RxBuffer.
00102       *
00103       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00104       *        gives a different behaviour:
00105       *
00106       *            ASYNC - Will attempt to read a single character, and return immediately
00107       *
00108       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00109       *
00110       *            SYNC_SLEEP - Will configure the event and block the current fiber until the
00111       *                         event is received.
00112       *
00113       * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, a character or MICROBIT_NO_DATA
00114       */
00115     int getc(MicroBitSerialMode mode = SYNC_SLEEP);
00116 
00117     /**
00118       * Places a single character into our transmission buffer,
00119       *
00120       * @param c the character to transmit
00121       *
00122       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00123       *        gives a different behaviour:
00124       *
00125       *            ASYNC - Will copy as many characters as it can into the buffer for transmission,
00126       *                    and return control to the user.
00127       *
00128       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00129       *
00130       *            SYNC_SLEEP - Will perform a cooperative blocking wait until all
00131       *                         given characters have been received by the connected
00132       *                         device.
00133       *
00134       * @return the number of characters written, or MICROBIT_NOT_SUPPORTED if there is
00135       *         no connected device, or the connected device has not enabled indications.
00136       */
00137     int putc(char c, MicroBitSerialMode mode = SYNC_SLEEP);
00138 
00139     /**
00140       * Copies characters into the buffer used for Transmitting to the central device.
00141       *
00142       * @param buf a buffer containing length number of bytes.
00143       * @param length the size of the buffer.
00144       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00145       *        gives a different behaviour:
00146       *
00147       *            ASYNC - Will copy as many characters as it can into the buffer for transmission,
00148       *                    and return control to the user.
00149       *
00150       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00151       *
00152       *            SYNC_SLEEP - Will perform a cooperative blocking wait until all
00153       *                         given characters have been received by the connected
00154       *                         device.
00155       *
00156       * @return the number of characters written, or MICROBIT_NOT_SUPPORTED if there is
00157       *         no connected device, or the connected device has not enabled indications.
00158       */
00159     int send(const uint8_t *buf, int length, MicroBitSerialMode mode = SYNC_SLEEP);
00160 
00161     /**
00162       * Copies characters into the buffer used for Transmitting to the central device.
00163       *
00164       * @param s the string to transmit
00165       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00166       *        gives a different behaviour:
00167       *
00168       *            ASYNC - Will copy as many characters as it can into the buffer for transmission,
00169       *                    and return control to the user.
00170       *
00171       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00172       *
00173       *            SYNC_SLEEP - Will perform a cooperative blocking wait until all
00174       *                         given characters have been received by the connected
00175       *                         device.
00176       *
00177       * @return the number of characters written, or MICROBIT_NOT_SUPPORTED if there is
00178       *         no connected device, or the connected device has not enabled indications.
00179       */
00180     int send(ManagedString s, MicroBitSerialMode mode = SYNC_SLEEP);
00181 
00182     /**
00183       * Reads a number of characters from the rxBuffer and fills user given buffer.
00184       *
00185       * @param buf a pointer to a buffer of len bytes.
00186       * @param len the size of the user allocated buffer
00187       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00188       *        gives a different behaviour:
00189       *
00190       *            ASYNC - Will attempt to read all available characters, and return immediately
00191       *                    until the buffer limit is reached
00192       *
00193       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00194       *
00195       *            SYNC_SLEEP - Will first of all determine whether the given number of characters
00196       *                         are available in our buffer, if not, it will set an event and sleep
00197       *                         until the number of characters are avaialable.
00198       *
00199       * @return the number of characters digested
00200       */
00201     int read(uint8_t *buf, int len, MicroBitSerialMode mode = SYNC_SLEEP);
00202 
00203     /**
00204       * Reads a number of characters from the rxBuffer and returns them as a ManagedString
00205       *
00206       * @param len the number of characters to read.
00207       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00208       *        gives a different behaviour:
00209       *
00210       *            ASYNC - Will attempt to read all available characters, and return immediately
00211       *                    until the buffer limit is reached
00212       *
00213       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00214       *
00215       *            SYNC_SLEEP - Will first of all determine whether the given number of characters
00216       *                         are available in our buffer, if not, it will set an event and sleep
00217       *                         until the number of characters are avaialable.
00218       *
00219       * @return an empty ManagedString on error, or a ManagedString containing characters
00220       */
00221     ManagedString read(int len, MicroBitSerialMode mode = SYNC_SLEEP);
00222 
00223     /**
00224       * Reads characters until a character matches one of the given delimeters
00225       *
00226       * @param delimeters the number of characters to match against
00227       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00228       *        gives a different behaviour:
00229       *
00230       *            ASYNC - Will attempt read the immediate buffer, and look for a match.
00231       *                    If there isn't, an empty ManagedString will be returned.
00232       *
00233       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00234       *
00235       *            SYNC_SLEEP - Will first of all consider the characters in the immediate buffer,
00236       *                         if a match is not found, it will block on an event, fired when a
00237       *                         character is matched.
00238       *
00239       * @return an empty ManagedString on error, or a ManagedString containing characters
00240       */
00241     ManagedString readUntil(ManagedString delimeters, MicroBitSerialMode mode = SYNC_SLEEP);
00242 
00243     /**
00244       * Configures an event to be fired on a match with one of the delimeters.
00245       *
00246       * @param delimeters the characters to match received characters against e.g. ManagedString("\r\n")
00247       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00248       *        gives a different behaviour:
00249       *
00250       *            ASYNC - Will configure the event and return immediately.
00251       *
00252       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00253       *
00254       *            SYNC_SLEEP - Will configure the event and block the current fiber until the
00255       *                         event is received.
00256       *
00257       * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
00258       *
00259       * @note delimeters are matched on a per byte basis.
00260       */
00261     int eventOn(ManagedString delimeters, MicroBitSerialMode mode = ASYNC);
00262 
00263     /**
00264       * Configures an event to be fired after "len" characters.
00265       *
00266       * @param len the number of characters to wait before triggering the event
00267       * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
00268       *        gives a different behaviour:
00269       *
00270       *            ASYNC - Will configure the event and return immediately.
00271       *
00272       *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
00273       *
00274       *            SYNC_SLEEP - Will configure the event and block the current fiber until the
00275       *                         event is received.
00276       *
00277       * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
00278       */
00279     int eventAfter(int len, MicroBitSerialMode mode = ASYNC);
00280 
00281     /**
00282       * Determines if we have space in our rxBuff.
00283       *
00284       * @return 1 if we have space, 0 if we do not.
00285       */
00286     int isReadable();
00287 
00288     /**
00289       * @return The currently buffered number of bytes in our rxBuff.
00290       */
00291     int rxBufferedSize ();
00292 
00293     /**
00294       * @return The currently buffered number of bytes in our txBuff.
00295       */
00296     int txBufferedSize ();
00297 };
00298 
00299 extern const uint8_t  UARTServiceBaseUUID[UUID::LENGTH_OF_LONG_UUID];
00300 extern const uint16_t UARTServiceShortUUID;
00301 extern const uint16_t UARTServiceTXCharacteristicShortUUID;
00302 extern const uint16_t UARTServiceRXCharacteristicShortUUID;
00303 
00304 extern const uint8_t  UARTServiceUUID[UUID::LENGTH_OF_LONG_UUID];
00305 extern const uint8_t  UARTServiceUUID_reversed[UUID::LENGTH_OF_LONG_UUID];
00306 
00307 extern const uint8_t  UARTServiceTXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID];
00308 extern const uint8_t  UARTServiceRXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID];
00309 
00310 #endif