Attempting to publish a tree
Dependencies: BLE_API mbed-dev-bin nRF51822
Fork of microbit-dal by
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 txCharacteristicHandle; 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 * @return the number of characters written (0, or 1). 00123 */ 00124 int putc(char c); 00125 00126 /** 00127 * Copies characters into the buffer used for Transmitting to the central device. 00128 * 00129 * @param buf a buffer containing length number of bytes. 00130 * @param length the size of the buffer. 00131 * 00132 * @return the number of characters copied into the buffer 00133 * 00134 * @note no modes for sending are available at the moment, due to interrupt overhead. 00135 */ 00136 int send(const uint8_t *buf, int length); 00137 00138 /** 00139 * Copies characters into the buffer used for Transmitting to the central device. 00140 * 00141 * @param s the string to transmit 00142 * 00143 * @return the number of characters copied into the buffer 00144 * 00145 * @note no modes for sending are available at the moment, due to interrupt overhead. 00146 */ 00147 int send(ManagedString s); 00148 00149 /** 00150 * Reads a number of characters from the rxBuffer and fills user given buffer. 00151 * 00152 * @param buf a pointer to a buffer of len bytes. 00153 * @param len the size of the user allocated buffer 00154 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode 00155 * gives a different behaviour: 00156 * 00157 * ASYNC - Will attempt to read all available characters, and return immediately 00158 * until the buffer limit is reached 00159 * 00160 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER 00161 * 00162 * SYNC_SLEEP - Will first of all determine whether the given number of characters 00163 * are available in our buffer, if not, it will set an event and sleep 00164 * until the number of characters are avaialable. 00165 * 00166 * @return the number of characters digested 00167 */ 00168 int read(uint8_t *buf, int len, MicroBitSerialMode mode = SYNC_SLEEP); 00169 00170 /** 00171 * Reads a number of characters from the rxBuffer and returns them as a ManagedString 00172 * 00173 * @param len the number of characters to read. 00174 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode 00175 * gives a different behaviour: 00176 * 00177 * ASYNC - Will attempt to read all available characters, and return immediately 00178 * until the buffer limit is reached 00179 * 00180 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER 00181 * 00182 * SYNC_SLEEP - Will first of all determine whether the given number of characters 00183 * are available in our buffer, if not, it will set an event and sleep 00184 * until the number of characters are avaialable. 00185 * 00186 * @return an empty ManagedString on error, or a ManagedString containing characters 00187 */ 00188 ManagedString read(int len, MicroBitSerialMode mode = SYNC_SLEEP); 00189 00190 /** 00191 * Reads characters until a character matches one of the given delimeters 00192 * 00193 * @param delimeters the number of characters to match against 00194 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode 00195 * gives a different behaviour: 00196 * 00197 * ASYNC - Will attempt read the immediate buffer, and look for a match. 00198 * If there isn't, an empty ManagedString will be returned. 00199 * 00200 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER 00201 * 00202 * SYNC_SLEEP - Will first of all consider the characters in the immediate buffer, 00203 * if a match is not found, it will block on an event, fired when a 00204 * character is matched. 00205 * 00206 * @return an empty ManagedString on error, or a ManagedString containing characters 00207 */ 00208 ManagedString readUntil(ManagedString delimeters, MicroBitSerialMode mode = SYNC_SLEEP); 00209 00210 /** 00211 * Configures an event to be fired on a match with one of the delimeters. 00212 * 00213 * @param delimeters the characters to match received characters against e.g. ManagedString("\r\n") 00214 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode 00215 * gives a different behaviour: 00216 * 00217 * ASYNC - Will configure the event and return immediately. 00218 * 00219 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER 00220 * 00221 * SYNC_SLEEP - Will configure the event and block the current fiber until the 00222 * event is received. 00223 * 00224 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK. 00225 * 00226 * @note delimeters are matched on a per byte basis. 00227 */ 00228 int eventOn(ManagedString delimeters, MicroBitSerialMode mode = ASYNC); 00229 00230 /** 00231 * Configures an event to be fired after "len" characters. 00232 * 00233 * @param len the number of characters to wait before triggering the event 00234 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode 00235 * gives a different behaviour: 00236 * 00237 * ASYNC - Will configure the event and return immediately. 00238 * 00239 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER 00240 * 00241 * SYNC_SLEEP - Will configure the event and block the current fiber until the 00242 * event is received. 00243 * 00244 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK. 00245 */ 00246 int eventAfter(int len, MicroBitSerialMode mode = ASYNC); 00247 00248 /** 00249 * Determines if we have space in our rxBuff. 00250 * 00251 * @return 1 if we have space, 0 if we do not. 00252 */ 00253 int isReadable(); 00254 00255 /** 00256 * @return The currently buffered number of bytes in our rxBuff. 00257 */ 00258 int rxBufferedSize (); 00259 00260 /** 00261 * @return The currently buffered number of bytes in our txBuff. 00262 */ 00263 int txBufferedSize (); 00264 }; 00265 00266 extern const uint8_t UARTServiceBaseUUID[UUID::LENGTH_OF_LONG_UUID]; 00267 extern const uint16_t UARTServiceShortUUID; 00268 extern const uint16_t UARTServiceTXCharacteristicShortUUID; 00269 extern const uint16_t UARTServiceRXCharacteristicShortUUID; 00270 00271 extern const uint8_t UARTServiceUUID[UUID::LENGTH_OF_LONG_UUID]; 00272 extern const uint8_t UARTServiceUUID_reversed[UUID::LENGTH_OF_LONG_UUID]; 00273 00274 extern const uint8_t UARTServiceTXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID]; 00275 extern const uint8_t UARTServiceRXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID]; 00276 00277 #endif
Generated on Tue Jul 12 2022 19:58:09 by 1.7.2