Francois Beaufort / microbit-ble-open

https://github.com/WebBluetoothCG/demos/pull/42

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal by Lancaster University

inc/drivers/MicroBitSerial.h@23:6055f6c19fa6, 2016-07-13 (annotated)

Committer:
LancasterUniversity
Date:
Wed Jul 13 12:17:56 2016 +0100
Revision:
23:6055f6c19fa6
Parent:
22:23d7b9a4b082
Child:
25:27299423d813
Synchronized with git rev 051abec1

Author: Martin Woolley

Changed BLE connection event constant names to match LU groovy naming convention

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jonathan Austin 1:8aa5cdb4ab67 1 /*
Jonathan Austin 1:8aa5cdb4ab67 2 The MIT License (MIT)
Jonathan Austin 1:8aa5cdb4ab67 3
Jonathan Austin 1:8aa5cdb4ab67 4 Copyright (c) 2016 British Broadcasting Corporation.
Jonathan Austin 1:8aa5cdb4ab67 5 This software is provided by Lancaster University by arrangement with the BBC.
Jonathan Austin 1:8aa5cdb4ab67 6
Jonathan Austin 1:8aa5cdb4ab67 7 Permission is hereby granted, free of charge, to any person obtaining a
Jonathan Austin 1:8aa5cdb4ab67 8 copy of this software and associated documentation files (the "Software"),
Jonathan Austin 1:8aa5cdb4ab67 9 to deal in the Software without restriction, including without limitation
Jonathan Austin 1:8aa5cdb4ab67 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
Jonathan Austin 1:8aa5cdb4ab67 11 and/or sell copies of the Software, and to permit persons to whom the
Jonathan Austin 1:8aa5cdb4ab67 12 Software is furnished to do so, subject to the following conditions:
Jonathan Austin 1:8aa5cdb4ab67 13
Jonathan Austin 1:8aa5cdb4ab67 14 The above copyright notice and this permission notice shall be included in
Jonathan Austin 1:8aa5cdb4ab67 15 all copies or substantial portions of the Software.
Jonathan Austin 1:8aa5cdb4ab67 16
Jonathan Austin 1:8aa5cdb4ab67 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Jonathan Austin 1:8aa5cdb4ab67 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Jonathan Austin 1:8aa5cdb4ab67 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
Jonathan Austin 1:8aa5cdb4ab67 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
Jonathan Austin 1:8aa5cdb4ab67 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 23 DEALINGS IN THE SOFTWARE.
Jonathan Austin 1:8aa5cdb4ab67 24 */
Jonathan Austin 1:8aa5cdb4ab67 25
Jonathan Austin 1:8aa5cdb4ab67 26 #ifndef MICROBIT_SERIAL_H
Jonathan Austin 1:8aa5cdb4ab67 27 #define MICROBIT_SERIAL_H
Jonathan Austin 1:8aa5cdb4ab67 28
Jonathan Austin 1:8aa5cdb4ab67 29 #include "mbed.h"
Jonathan Austin 1:8aa5cdb4ab67 30 #include "ManagedString.h"
Jonathan Austin 1:8aa5cdb4ab67 31
Jonathan Austin 1:8aa5cdb4ab67 32 #define MICROBIT_SERIAL_DEFAULT_BAUD_RATE 115200
Jonathan Austin 1:8aa5cdb4ab67 33 #define MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE 20
Jonathan Austin 1:8aa5cdb4ab67 34
Jonathan Austin 1:8aa5cdb4ab67 35 #define MICROBIT_SERIAL_EVT_DELIM_MATCH 1
Jonathan Austin 1:8aa5cdb4ab67 36 #define MICROBIT_SERIAL_EVT_HEAD_MATCH 2
Jonathan Austin 1:8aa5cdb4ab67 37 #define MICROBIT_SERIAL_EVT_RX_FULL 3
Jonathan Austin 1:8aa5cdb4ab67 38
Jonathan Austin 1:8aa5cdb4ab67 39 #define MICROBIT_SERIAL_RX_IN_USE 1
Jonathan Austin 1:8aa5cdb4ab67 40 #define MICROBIT_SERIAL_TX_IN_USE 2
Jonathan Austin 1:8aa5cdb4ab67 41 #define MICROBIT_SERIAL_RX_BUFF_INIT 4
Jonathan Austin 1:8aa5cdb4ab67 42 #define MICROBIT_SERIAL_TX_BUFF_INIT 8
Jonathan Austin 1:8aa5cdb4ab67 43
Jonathan Austin 1:8aa5cdb4ab67 44
Jonathan Austin 1:8aa5cdb4ab67 45 enum MicroBitSerialMode
Jonathan Austin 1:8aa5cdb4ab67 46 {
Jonathan Austin 1:8aa5cdb4ab67 47 ASYNC,
Jonathan Austin 1:8aa5cdb4ab67 48 SYNC_SPINWAIT,
Jonathan Austin 1:8aa5cdb4ab67 49 SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 50 };
Jonathan Austin 1:8aa5cdb4ab67 51
Jonathan Austin 1:8aa5cdb4ab67 52 /**
Jonathan Austin 1:8aa5cdb4ab67 53 * Class definition for MicroBitSerial.
Jonathan Austin 1:8aa5cdb4ab67 54 *
Jonathan Austin 1:8aa5cdb4ab67 55 * Represents an instance of RawSerial which accepts micro:bit specific data types.
Jonathan Austin 1:8aa5cdb4ab67 56 */
Jonathan Austin 1:8aa5cdb4ab67 57 class MicroBitSerial : public RawSerial
Jonathan Austin 1:8aa5cdb4ab67 58 {
Jonathan Austin 1:8aa5cdb4ab67 59
Jonathan Austin 1:8aa5cdb4ab67 60 //holds that state of the mutex locks for all MicroBitSerial instances.
Jonathan Austin 1:8aa5cdb4ab67 61 static uint8_t status;
Jonathan Austin 1:8aa5cdb4ab67 62
Jonathan Austin 1:8aa5cdb4ab67 63 //holds the state of the baudrate for all MicroBitSerial instances.
Jonathan Austin 1:8aa5cdb4ab67 64 static int baudrate;
Jonathan Austin 1:8aa5cdb4ab67 65
Jonathan Austin 1:8aa5cdb4ab67 66 //delimeters used for matching on receive.
Jonathan Austin 1:8aa5cdb4ab67 67 ManagedString delimeters;
Jonathan Austin 1:8aa5cdb4ab67 68
Jonathan Austin 1:8aa5cdb4ab67 69 //a variable used when a user calls the eventAfter() method.
Jonathan Austin 1:8aa5cdb4ab67 70 int rxBuffHeadMatch;
Jonathan Austin 1:8aa5cdb4ab67 71
Jonathan Austin 1:8aa5cdb4ab67 72 uint8_t *rxBuff;
Jonathan Austin 1:8aa5cdb4ab67 73 uint8_t rxBuffSize;
Jonathan Austin 1:8aa5cdb4ab67 74 volatile uint16_t rxBuffHead;
Jonathan Austin 1:8aa5cdb4ab67 75 uint16_t rxBuffTail;
Jonathan Austin 1:8aa5cdb4ab67 76
Jonathan Austin 1:8aa5cdb4ab67 77
Jonathan Austin 1:8aa5cdb4ab67 78 uint8_t *txBuff;
Jonathan Austin 1:8aa5cdb4ab67 79 uint8_t txBuffSize;
Jonathan Austin 1:8aa5cdb4ab67 80 uint16_t txBuffHead;
Jonathan Austin 1:8aa5cdb4ab67 81 volatile uint16_t txBuffTail;
Jonathan Austin 1:8aa5cdb4ab67 82
Jonathan Austin 1:8aa5cdb4ab67 83 /**
Jonathan Austin 1:8aa5cdb4ab67 84 * An internal interrupt callback for MicroBitSerial configured for when a
Jonathan Austin 1:8aa5cdb4ab67 85 * character is received.
Jonathan Austin 1:8aa5cdb4ab67 86 *
Jonathan Austin 1:8aa5cdb4ab67 87 * Each time a character is received fill our circular buffer!
Jonathan Austin 1:8aa5cdb4ab67 88 */
Jonathan Austin 1:8aa5cdb4ab67 89 void dataReceived();
Jonathan Austin 1:8aa5cdb4ab67 90
Jonathan Austin 1:8aa5cdb4ab67 91 /**
Jonathan Austin 1:8aa5cdb4ab67 92 * An internal interrupt callback for MicroBitSerial.
Jonathan Austin 1:8aa5cdb4ab67 93 *
Jonathan Austin 1:8aa5cdb4ab67 94 * Each time the Serial module's buffer is empty, write a character if we have
Jonathan Austin 1:8aa5cdb4ab67 95 * characters to write.
Jonathan Austin 1:8aa5cdb4ab67 96 */
Jonathan Austin 1:8aa5cdb4ab67 97 void dataWritten();
Jonathan Austin 1:8aa5cdb4ab67 98
Jonathan Austin 1:8aa5cdb4ab67 99 /**
Jonathan Austin 1:8aa5cdb4ab67 100 * An internal method to configure an interrupt on tx buffer and also
Jonathan Austin 1:8aa5cdb4ab67 101 * a best effort copy operation to move bytes from a user buffer to our txBuff
Jonathan Austin 1:8aa5cdb4ab67 102 *
Jonathan Austin 1:8aa5cdb4ab67 103 * @param string a pointer to the first character of the users' buffer.
Jonathan Austin 1:8aa5cdb4ab67 104 *
Jonathan Austin 1:8aa5cdb4ab67 105 * @param len the length of the string, and ultimately the maximum number of bytes
Jonathan Austin 1:8aa5cdb4ab67 106 * that will be copied dependent on the state of txBuff
Jonathan Austin 1:8aa5cdb4ab67 107 *
Jonathan Austin 1:8aa5cdb4ab67 108 * @return the number of bytes copied into the buffer.
Jonathan Austin 1:8aa5cdb4ab67 109 */
LancasterUniversity 23:6055f6c19fa6 110 int setTxInterrupt(uint8_t *string, int len);
Jonathan Austin 1:8aa5cdb4ab67 111
Jonathan Austin 1:8aa5cdb4ab67 112 /**
Jonathan Austin 1:8aa5cdb4ab67 113 * Locks the mutex so that others can't use this serial instance for reception
Jonathan Austin 1:8aa5cdb4ab67 114 */
Jonathan Austin 1:8aa5cdb4ab67 115 void lockRx();
Jonathan Austin 1:8aa5cdb4ab67 116
Jonathan Austin 1:8aa5cdb4ab67 117 /**
Jonathan Austin 1:8aa5cdb4ab67 118 * Locks the mutex so that others can't use this serial instance for transmission
Jonathan Austin 1:8aa5cdb4ab67 119 */
Jonathan Austin 1:8aa5cdb4ab67 120 void lockTx();
Jonathan Austin 1:8aa5cdb4ab67 121
Jonathan Austin 1:8aa5cdb4ab67 122 /**
Jonathan Austin 1:8aa5cdb4ab67 123 * Unlocks the mutex so that others can use this serial instance for reception
Jonathan Austin 1:8aa5cdb4ab67 124 */
Jonathan Austin 1:8aa5cdb4ab67 125 void unlockRx();
Jonathan Austin 1:8aa5cdb4ab67 126
Jonathan Austin 1:8aa5cdb4ab67 127 /**
Jonathan Austin 1:8aa5cdb4ab67 128 * Unlocks the mutex so that others can use this serial instance for transmission
Jonathan Austin 1:8aa5cdb4ab67 129 */
Jonathan Austin 1:8aa5cdb4ab67 130 void unlockTx();
Jonathan Austin 1:8aa5cdb4ab67 131
Jonathan Austin 1:8aa5cdb4ab67 132 /**
Jonathan Austin 1:8aa5cdb4ab67 133 * We do not want to always have our buffers initialised, especially if users to not
Jonathan Austin 1:8aa5cdb4ab67 134 * use them. We only bring them up on demand.
Jonathan Austin 1:8aa5cdb4ab67 135 */
Jonathan Austin 1:8aa5cdb4ab67 136 int initialiseRx();
Jonathan Austin 1:8aa5cdb4ab67 137
Jonathan Austin 1:8aa5cdb4ab67 138 /**
Jonathan Austin 1:8aa5cdb4ab67 139 * We do not want to always have our buffers initialised, especially if users to not
Jonathan Austin 1:8aa5cdb4ab67 140 * use them. We only bring them up on demand.
Jonathan Austin 1:8aa5cdb4ab67 141 */
Jonathan Austin 1:8aa5cdb4ab67 142 int initialiseTx();
Jonathan Austin 1:8aa5cdb4ab67 143
Jonathan Austin 1:8aa5cdb4ab67 144 /**
Jonathan Austin 1:8aa5cdb4ab67 145 * An internal method that either spin waits if mode is set to SYNC_SPINWAIT
Jonathan Austin 1:8aa5cdb4ab67 146 * or puts the fiber to sleep if the mode is set to SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 147 *
Jonathan Austin 1:8aa5cdb4ab67 148 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 149 */
Jonathan Austin 1:8aa5cdb4ab67 150 void send(MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 151
Jonathan Austin 1:8aa5cdb4ab67 152 /**
Jonathan Austin 1:8aa5cdb4ab67 153 * Reads a single character from the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 154 *
Jonathan Austin 1:8aa5cdb4ab67 155 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 156 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 157 *
Jonathan Austin 1:8aa5cdb4ab67 158 * ASYNC - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 159 * are no characters to be read, a value of zero is returned immediately.
Jonathan Austin 1:8aa5cdb4ab67 160 *
Jonathan Austin 1:8aa5cdb4ab67 161 * SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 162 * are no characters to be read, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 163 * (lock up the processor) until a character is available.
Jonathan Austin 1:8aa5cdb4ab67 164 *
Jonathan Austin 1:8aa5cdb4ab67 165 * SYNC_SLEEP - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 166 * are no characters to be read, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 167 * until there is a character available.
Jonathan Austin 1:8aa5cdb4ab67 168 *
Jonathan Austin 1:8aa5cdb4ab67 169 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 170 *
Jonathan Austin 1:8aa5cdb4ab67 171 * @return a character from the circular buffer, or MICROBIT_NO_DATA is there
Jonathan Austin 1:8aa5cdb4ab67 172 * are no characters in the buffer.
Jonathan Austin 1:8aa5cdb4ab67 173 */
Jonathan Austin 1:8aa5cdb4ab67 174 int getChar(MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 175
Jonathan Austin 1:8aa5cdb4ab67 176 /**
Jonathan Austin 1:8aa5cdb4ab67 177 * An internal method that copies values from a circular buffer to a linear buffer.
Jonathan Austin 1:8aa5cdb4ab67 178 *
Jonathan Austin 1:8aa5cdb4ab67 179 * @param circularBuff a pointer to the source circular buffer
Jonathan Austin 1:8aa5cdb4ab67 180 *
Jonathan Austin 1:8aa5cdb4ab67 181 * @param circularBuffSize the size of the circular buffer
Jonathan Austin 1:8aa5cdb4ab67 182 *
Jonathan Austin 1:8aa5cdb4ab67 183 * @param linearBuff a pointer to the destination linear buffer
Jonathan Austin 1:8aa5cdb4ab67 184 *
Jonathan Austin 1:8aa5cdb4ab67 185 * @param tailPosition the tail position in the circular buffer you want to copy from
Jonathan Austin 1:8aa5cdb4ab67 186 *
Jonathan Austin 1:8aa5cdb4ab67 187 * @param headPosition the head position in the circular buffer you want to copy to
Jonathan Austin 1:8aa5cdb4ab67 188 *
Jonathan Austin 1:8aa5cdb4ab67 189 * @note this method assumes that the linear buffer has the appropriate amount of
Jonathan Austin 1:8aa5cdb4ab67 190 * memory to contain the copy operation
Jonathan Austin 1:8aa5cdb4ab67 191 */
Jonathan Austin 1:8aa5cdb4ab67 192 void circularCopy(uint8_t *circularBuff, uint8_t circularBuffSize, uint8_t *linearBuff, uint16_t tailPosition, uint16_t headPosition);
Jonathan Austin 1:8aa5cdb4ab67 193
Jonathan Austin 1:8aa5cdb4ab67 194 public:
Jonathan Austin 1:8aa5cdb4ab67 195
Jonathan Austin 1:8aa5cdb4ab67 196 /**
Jonathan Austin 1:8aa5cdb4ab67 197 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 198 * Create an instance of MicroBitSerial
Jonathan Austin 1:8aa5cdb4ab67 199 *
Jonathan Austin 1:8aa5cdb4ab67 200 * @param tx the Pin to be used for transmission
Jonathan Austin 1:8aa5cdb4ab67 201 *
Jonathan Austin 1:8aa5cdb4ab67 202 * @param rx the Pin to be used for receiving data
Jonathan Austin 1:8aa5cdb4ab67 203 *
Jonathan Austin 1:8aa5cdb4ab67 204 * @param rxBufferSize the size of the buffer to be used for receiving bytes
Jonathan Austin 1:8aa5cdb4ab67 205 *
Jonathan Austin 1:8aa5cdb4ab67 206 * @param txBufferSize the size of the buffer to be used for transmitting bytes
Jonathan Austin 1:8aa5cdb4ab67 207 *
Jonathan Austin 1:8aa5cdb4ab67 208 * @code
Jonathan Austin 1:8aa5cdb4ab67 209 * MicroBitSerial serial(USBTX, USBRX);
Jonathan Austin 1:8aa5cdb4ab67 210 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 211 * @note the default baud rate is 115200. More API details can be found:
Jonathan Austin 1:8aa5cdb4ab67 212 * -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/SerialBase.h
Jonathan Austin 1:8aa5cdb4ab67 213 * -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/RawSerial.h
Jonathan Austin 1:8aa5cdb4ab67 214 *
Jonathan Austin 1:8aa5cdb4ab67 215 * Buffers aren't allocated until the first send or receive respectively.
Jonathan Austin 1:8aa5cdb4ab67 216 */
Jonathan Austin 1:8aa5cdb4ab67 217 MicroBitSerial(PinName tx, PinName rx, uint8_t rxBufferSize = MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE, uint8_t txBufferSize = MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE);
Jonathan Austin 1:8aa5cdb4ab67 218
Jonathan Austin 1:8aa5cdb4ab67 219 /**
Jonathan Austin 1:8aa5cdb4ab67 220 * Sends a single character over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 221 *
Jonathan Austin 1:8aa5cdb4ab67 222 * @param c the character to send
Jonathan Austin 1:8aa5cdb4ab67 223 *
Jonathan Austin 1:8aa5cdb4ab67 224 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 225 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 226 *
Jonathan Austin 1:8aa5cdb4ab67 227 * ASYNC - the character is copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 228 *
Jonathan Austin 1:8aa5cdb4ab67 229 * SYNC_SPINWAIT - the character is copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 230 * will spin (lock up the processor) until the character has
Jonathan Austin 1:8aa5cdb4ab67 231 * been sent.
Jonathan Austin 1:8aa5cdb4ab67 232 *
Jonathan Austin 1:8aa5cdb4ab67 233 * SYNC_SLEEP - the character is copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 234 * until the character has been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 235 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 236 *
Jonathan Austin 1:8aa5cdb4ab67 237 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 238 *
Jonathan Austin 1:8aa5cdb4ab67 239 * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 240 * is using the serial instance for transmission.
Jonathan Austin 1:8aa5cdb4ab67 241 */
Jonathan Austin 1:8aa5cdb4ab67 242 int sendChar(char c, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 243
Jonathan Austin 1:8aa5cdb4ab67 244 /**
Jonathan Austin 1:8aa5cdb4ab67 245 * Sends a ManagedString over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 246 *
Jonathan Austin 1:8aa5cdb4ab67 247 * @param s the string to send
Jonathan Austin 1:8aa5cdb4ab67 248 *
Jonathan Austin 1:8aa5cdb4ab67 249 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 250 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 251 *
Jonathan Austin 1:8aa5cdb4ab67 252 * ASYNC - bytes are copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 253 *
Jonathan Austin 1:8aa5cdb4ab67 254 * SYNC_SPINWAIT - bytes are copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 255 * will spin (lock up the processor) until all bytes
Jonathan Austin 1:8aa5cdb4ab67 256 * have been sent.
Jonathan Austin 1:8aa5cdb4ab67 257 *
Jonathan Austin 1:8aa5cdb4ab67 258 * SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 259 * until all bytes have been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 260 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 261 *
Jonathan Austin 1:8aa5cdb4ab67 262 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 263 *
Jonathan Austin 1:8aa5cdb4ab67 264 * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 265 * is using the serial instance for transmission.
Jonathan Austin 1:8aa5cdb4ab67 266 */
Jonathan Austin 1:8aa5cdb4ab67 267 int send(ManagedString s, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 268
Jonathan Austin 1:8aa5cdb4ab67 269 /**
Jonathan Austin 1:8aa5cdb4ab67 270 * Sends a buffer of known length over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 271 *
Jonathan Austin 1:8aa5cdb4ab67 272 * @param buffer a pointer to the first character of the buffer
Jonathan Austin 1:8aa5cdb4ab67 273 *
Jonathan Austin 1:8aa5cdb4ab67 274 * @param len the number of bytes that are safely available to read.
Jonathan Austin 1:8aa5cdb4ab67 275 *
Jonathan Austin 1:8aa5cdb4ab67 276 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 277 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 278 *
Jonathan Austin 1:8aa5cdb4ab67 279 * ASYNC - bytes are copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 280 *
Jonathan Austin 1:8aa5cdb4ab67 281 * SYNC_SPINWAIT - bytes are copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 282 * will spin (lock up the processor) until all bytes
Jonathan Austin 1:8aa5cdb4ab67 283 * have been sent.
Jonathan Austin 1:8aa5cdb4ab67 284 *
Jonathan Austin 1:8aa5cdb4ab67 285 * SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 286 * until all bytes have been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 287 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 288 *
Jonathan Austin 1:8aa5cdb4ab67 289 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 290 *
Jonathan Austin 1:8aa5cdb4ab67 291 * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 292 * is using the serial instance for transmission.
Jonathan Austin 1:8aa5cdb4ab67 293 */
Jonathan Austin 1:8aa5cdb4ab67 294 int send(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 295
Jonathan Austin 1:8aa5cdb4ab67 296 /**
Jonathan Austin 1:8aa5cdb4ab67 297 * Reads a single character from the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 298 *
Jonathan Austin 1:8aa5cdb4ab67 299 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 300 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 301 *
Jonathan Austin 1:8aa5cdb4ab67 302 * ASYNC - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 303 * are no characters to be read, a value of MICROBIT_NO_DATA is returned immediately.
Jonathan Austin 1:8aa5cdb4ab67 304 *
Jonathan Austin 1:8aa5cdb4ab67 305 * SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 306 * are no characters to be read, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 307 * (lock up the processor) until a character is available.
Jonathan Austin 1:8aa5cdb4ab67 308 *
Jonathan Austin 1:8aa5cdb4ab67 309 * SYNC_SLEEP - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 310 * are no characters to be read, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 311 * until there is a character available.
Jonathan Austin 1:8aa5cdb4ab67 312 *
Jonathan Austin 1:8aa5cdb4ab67 313 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 314 *
Jonathan Austin 1:8aa5cdb4ab67 315 * @return a character, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for reception,
Jonathan Austin 1:8aa5cdb4ab67 316 * MICROBIT_NO_RESOURCES if buffer allocation did not complete successfully, or MICROBIT_NO_DATA if
Jonathan Austin 1:8aa5cdb4ab67 317 * the rx buffer is empty and the mode given is ASYNC.
Jonathan Austin 1:8aa5cdb4ab67 318 */
Jonathan Austin 1:8aa5cdb4ab67 319 int read(MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 320
Jonathan Austin 1:8aa5cdb4ab67 321 /**
Jonathan Austin 1:8aa5cdb4ab67 322 * Reads multiple characters from the rxBuff and returns them as a ManagedString
Jonathan Austin 1:8aa5cdb4ab67 323 *
Jonathan Austin 1:8aa5cdb4ab67 324 * @param size the number of characters to read.
Jonathan Austin 1:8aa5cdb4ab67 325 *
Jonathan Austin 1:8aa5cdb4ab67 326 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 327 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 328 *
Jonathan Austin 1:8aa5cdb4ab67 329 * ASYNC - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 330 * a ManagedString with the expected size. Otherwise, it will read however
Jonathan Austin 1:8aa5cdb4ab67 331 * many characters there are available.
Jonathan Austin 1:8aa5cdb4ab67 332 *
Jonathan Austin 1:8aa5cdb4ab67 333 * SYNC_SPINWAIT - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 334 * a ManagedString with the expected size. Otherwise, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 335 * (lock up the processor) until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 336 *
Jonathan Austin 1:8aa5cdb4ab67 337 * SYNC_SLEEP - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 338 * a ManagedString with the expected size. Otherwise, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 339 * until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 340 *
Jonathan Austin 1:8aa5cdb4ab67 341 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 342 *
Jonathan Austin 1:8aa5cdb4ab67 343 * @return A ManagedString, or an empty ManagedString if an error was encountered during the read.
Jonathan Austin 1:8aa5cdb4ab67 344 */
Jonathan Austin 1:8aa5cdb4ab67 345 ManagedString read(int size, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 346
Jonathan Austin 1:8aa5cdb4ab67 347 /**
Jonathan Austin 1:8aa5cdb4ab67 348 * Reads multiple characters from the rxBuff and fills a user buffer.
Jonathan Austin 1:8aa5cdb4ab67 349 *
Jonathan Austin 1:8aa5cdb4ab67 350 * @param buffer a pointer to a user allocated buffer.
Jonathan Austin 1:8aa5cdb4ab67 351 *
Jonathan Austin 1:8aa5cdb4ab67 352 * @param bufferLen the amount of data that can be safely stored
Jonathan Austin 1:8aa5cdb4ab67 353 *
Jonathan Austin 1:8aa5cdb4ab67 354 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 355 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 356 *
Jonathan Austin 1:8aa5cdb4ab67 357 * ASYNC - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 358 * the given buffer. Otherwise, it will fill the buffer with however
Jonathan Austin 1:8aa5cdb4ab67 359 * many characters there are available.
Jonathan Austin 1:8aa5cdb4ab67 360 *
Jonathan Austin 1:8aa5cdb4ab67 361 * SYNC_SPINWAIT - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 362 * the given buffer. Otherwise, this method will spin (lock up the processor)
Jonathan Austin 1:8aa5cdb4ab67 363 * and fill the buffer until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 364 *
Jonathan Austin 1:8aa5cdb4ab67 365 * SYNC_SLEEP - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 366 * the given buffer. Otherwise, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 367 * until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 368 *
Jonathan Austin 1:8aa5cdb4ab67 369 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 370 *
Jonathan Austin 1:8aa5cdb4ab67 371 * @return the number of characters read, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 372 * is using the instance for receiving.
Jonathan Austin 1:8aa5cdb4ab67 373 */
Jonathan Austin 1:8aa5cdb4ab67 374 int read(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 375
Jonathan Austin 1:8aa5cdb4ab67 376 /**
Jonathan Austin 1:8aa5cdb4ab67 377 * Reads until one of the delimeters matches a character in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 378 *
Jonathan Austin 1:8aa5cdb4ab67 379 * @param delimeters a ManagedString containing a sequence of delimeter characters e.g. ManagedString("\r\n")
Jonathan Austin 1:8aa5cdb4ab67 380 *
Jonathan Austin 1:8aa5cdb4ab67 381 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 382 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 383 *
Jonathan Austin 1:8aa5cdb4ab67 384 * ASYNC - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 385 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 386 * Otherwise, it will return an Empty ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 387 *
Jonathan Austin 1:8aa5cdb4ab67 388 * SYNC_SPINWAIT - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 389 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 390 * Otherwise, this method will spin (lock up the processor) until a
Jonathan Austin 1:8aa5cdb4ab67 391 * received character matches one of the delimeters.
Jonathan Austin 1:8aa5cdb4ab67 392 *
Jonathan Austin 1:8aa5cdb4ab67 393 * SYNC_SLEEP - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 394 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 395 * Otherwise, the calling fiber sleeps until a character matching one
Jonathan Austin 1:8aa5cdb4ab67 396 * of the delimeters is seen.
Jonathan Austin 1:8aa5cdb4ab67 397 *
Jonathan Austin 1:8aa5cdb4ab67 398 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 399 *
Jonathan Austin 1:8aa5cdb4ab67 400 * @return A ManagedString containing the characters up to a delimeter, or an Empty ManagedString,
Jonathan Austin 1:8aa5cdb4ab67 401 * if another fiber is currently using this instance for reception.
Jonathan Austin 1:8aa5cdb4ab67 402 *
Jonathan Austin 1:8aa5cdb4ab67 403 * @note delimeters are matched on a per byte basis.
Jonathan Austin 1:8aa5cdb4ab67 404 */
Jonathan Austin 1:8aa5cdb4ab67 405 ManagedString readUntil(ManagedString delimeters, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 406
Jonathan Austin 1:8aa5cdb4ab67 407 /**
Jonathan Austin 1:8aa5cdb4ab67 408 * A wrapper around the inherited method "baud" so we can trap the baud rate
Jonathan Austin 1:8aa5cdb4ab67 409 * as it changes and restore it if redirect() is called.
Jonathan Austin 1:8aa5cdb4ab67 410 *
Jonathan Austin 1:8aa5cdb4ab67 411 * @param baudrate the new baudrate. See:
Jonathan Austin 1:8aa5cdb4ab67 412 * - https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/targets/hal/TARGET_NORDIC/TARGET_MCU_NRF51822/serial_api.c
Jonathan Austin 1:8aa5cdb4ab67 413 * for permitted baud rates.
Jonathan Austin 1:8aa5cdb4ab67 414 *
Jonathan Austin 1:8aa5cdb4ab67 415 * @return MICROBIT_INVALID_PARAMETER if baud rate is less than 0, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 416 *
Jonathan Austin 1:8aa5cdb4ab67 417 * @note the underlying implementation chooses the first allowable rate at or above that requested.
Jonathan Austin 1:8aa5cdb4ab67 418 */
Jonathan Austin 1:8aa5cdb4ab67 419 void baud(int baudrate);
Jonathan Austin 1:8aa5cdb4ab67 420
Jonathan Austin 1:8aa5cdb4ab67 421 /**
Jonathan Austin 1:8aa5cdb4ab67 422 * A way of dynamically configuring the serial instance to use pins other than USBTX and USBRX.
Jonathan Austin 1:8aa5cdb4ab67 423 *
Jonathan Austin 1:8aa5cdb4ab67 424 * @param tx the new transmission pin.
Jonathan Austin 1:8aa5cdb4ab67 425 *
Jonathan Austin 1:8aa5cdb4ab67 426 * @param rx the new reception pin.
Jonathan Austin 1:8aa5cdb4ab67 427 *
Jonathan Austin 1:8aa5cdb4ab67 428 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently transmitting or receiving, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 429 */
Jonathan Austin 1:8aa5cdb4ab67 430 int redirect(PinName tx, PinName rx);
Jonathan Austin 1:8aa5cdb4ab67 431
Jonathan Austin 1:8aa5cdb4ab67 432 /**
Jonathan Austin 1:8aa5cdb4ab67 433 * Configures an event to be fired after "len" characters.
Jonathan Austin 1:8aa5cdb4ab67 434 *
Jonathan Austin 1:8aa5cdb4ab67 435 * @param len the number of characters to wait before triggering the event.
Jonathan Austin 1:8aa5cdb4ab67 436 *
Jonathan Austin 1:8aa5cdb4ab67 437 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 438 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 439 *
Jonathan Austin 1:8aa5cdb4ab67 440 * ASYNC - Will configure the event and return immediately.
Jonathan Austin 1:8aa5cdb4ab67 441 *
Jonathan Austin 1:8aa5cdb4ab67 442 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
Jonathan Austin 1:8aa5cdb4ab67 443 *
Jonathan Austin 1:8aa5cdb4ab67 444 * SYNC_SLEEP - Will configure the event and block the current fiber until the
Jonathan Austin 1:8aa5cdb4ab67 445 * event is received.
Jonathan Austin 1:8aa5cdb4ab67 446 *
Jonathan Austin 1:8aa5cdb4ab67 447 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 448 */
Jonathan Austin 1:8aa5cdb4ab67 449 int eventAfter(int len, MicroBitSerialMode mode = ASYNC);
Jonathan Austin 1:8aa5cdb4ab67 450
Jonathan Austin 1:8aa5cdb4ab67 451 /**
Jonathan Austin 1:8aa5cdb4ab67 452 * Configures an event to be fired on a match with one of the delimeters.
Jonathan Austin 1:8aa5cdb4ab67 453 *
Jonathan Austin 1:8aa5cdb4ab67 454 * @param delimeters the characters to match received characters against e.g. ManagedString("\r\n")
Jonathan Austin 1:8aa5cdb4ab67 455 *
Jonathan Austin 1:8aa5cdb4ab67 456 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 457 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 458 *
Jonathan Austin 1:8aa5cdb4ab67 459 * ASYNC - Will configure the event and return immediately.
Jonathan Austin 1:8aa5cdb4ab67 460 *
Jonathan Austin 1:8aa5cdb4ab67 461 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
Jonathan Austin 1:8aa5cdb4ab67 462 *
Jonathan Austin 1:8aa5cdb4ab67 463 * SYNC_SLEEP - Will configure the event and block the current fiber until the
Jonathan Austin 1:8aa5cdb4ab67 464 * event is received.
Jonathan Austin 1:8aa5cdb4ab67 465 *
Jonathan Austin 1:8aa5cdb4ab67 466 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 467 *
Jonathan Austin 1:8aa5cdb4ab67 468 * @note delimeters are matched on a per byte basis.
Jonathan Austin 1:8aa5cdb4ab67 469 */
Jonathan Austin 1:8aa5cdb4ab67 470 int eventOn(ManagedString delimeters, MicroBitSerialMode mode = ASYNC);
Jonathan Austin 1:8aa5cdb4ab67 471
Jonathan Austin 1:8aa5cdb4ab67 472 /**
Jonathan Austin 1:8aa5cdb4ab67 473 * Determines whether there is any data waiting in our Rx buffer.
Jonathan Austin 1:8aa5cdb4ab67 474 *
Jonathan Austin 1:8aa5cdb4ab67 475 * @return 1 if we have space, 0 if we do not.
Jonathan Austin 1:8aa5cdb4ab67 476 *
Jonathan Austin 1:8aa5cdb4ab67 477 * @note We do not wrap the super's readable() method as we don't want to
Jonathan Austin 1:8aa5cdb4ab67 478 * interfere with communities that use manual calls to serial.readable().
Jonathan Austin 1:8aa5cdb4ab67 479 */
Jonathan Austin 1:8aa5cdb4ab67 480 int isReadable();
Jonathan Austin 1:8aa5cdb4ab67 481
Jonathan Austin 1:8aa5cdb4ab67 482 /**
Jonathan Austin 1:8aa5cdb4ab67 483 * Determines if we have space in our txBuff.
Jonathan Austin 1:8aa5cdb4ab67 484 *
Jonathan Austin 1:8aa5cdb4ab67 485 * @return 1 if we have space, 0 if we do not.
Jonathan Austin 1:8aa5cdb4ab67 486 *
Jonathan Austin 1:8aa5cdb4ab67 487 * @note We do not wrap the super's writeable() method as we don't want to
Jonathan Austin 1:8aa5cdb4ab67 488 * interfere with communities that use manual calls to serial.writeable().
Jonathan Austin 1:8aa5cdb4ab67 489 */
Jonathan Austin 1:8aa5cdb4ab67 490 int isWriteable();
Jonathan Austin 1:8aa5cdb4ab67 491
Jonathan Austin 1:8aa5cdb4ab67 492 /**
Jonathan Austin 1:8aa5cdb4ab67 493 * Reconfigures the size of our rxBuff
Jonathan Austin 1:8aa5cdb4ab67 494 *
Jonathan Austin 1:8aa5cdb4ab67 495 * @param size the new size for our rxBuff
Jonathan Austin 1:8aa5cdb4ab67 496 *
Jonathan Austin 1:8aa5cdb4ab67 497 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 498 * for reception, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 499 */
Jonathan Austin 1:8aa5cdb4ab67 500 int setRxBufferSize(uint8_t size);
Jonathan Austin 1:8aa5cdb4ab67 501
Jonathan Austin 1:8aa5cdb4ab67 502 /**
Jonathan Austin 1:8aa5cdb4ab67 503 * Reconfigures the size of our txBuff
Jonathan Austin 1:8aa5cdb4ab67 504 *
Jonathan Austin 1:8aa5cdb4ab67 505 * @param size the new size for our txBuff
Jonathan Austin 1:8aa5cdb4ab67 506 *
Jonathan Austin 1:8aa5cdb4ab67 507 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 508 * for transmission, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 509 */
Jonathan Austin 1:8aa5cdb4ab67 510 int setTxBufferSize(uint8_t size);
Jonathan Austin 1:8aa5cdb4ab67 511
Jonathan Austin 1:8aa5cdb4ab67 512 /**
Jonathan Austin 1:8aa5cdb4ab67 513 * The size of our rx buffer in bytes.
Jonathan Austin 1:8aa5cdb4ab67 514 *
Jonathan Austin 1:8aa5cdb4ab67 515 * @return the current size of rxBuff in bytes
Jonathan Austin 1:8aa5cdb4ab67 516 */
Jonathan Austin 1:8aa5cdb4ab67 517 int getRxBufferSize();
Jonathan Austin 1:8aa5cdb4ab67 518
Jonathan Austin 1:8aa5cdb4ab67 519 /**
Jonathan Austin 1:8aa5cdb4ab67 520 * The size of our tx buffer in bytes.
Jonathan Austin 1:8aa5cdb4ab67 521 *
Jonathan Austin 1:8aa5cdb4ab67 522 * @return the current size of txBuff in bytes
Jonathan Austin 1:8aa5cdb4ab67 523 */
Jonathan Austin 1:8aa5cdb4ab67 524 int getTxBufferSize();
Jonathan Austin 1:8aa5cdb4ab67 525
Jonathan Austin 1:8aa5cdb4ab67 526 /**
Jonathan Austin 1:8aa5cdb4ab67 527 * Sets the tail to match the head of our circular buffer for reception,
Jonathan Austin 1:8aa5cdb4ab67 528 * effectively clearing the reception buffer.
Jonathan Austin 1:8aa5cdb4ab67 529 *
Jonathan Austin 1:8aa5cdb4ab67 530 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 531 * for reception, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 532 */
Jonathan Austin 1:8aa5cdb4ab67 533 int clearRxBuffer();
Jonathan Austin 1:8aa5cdb4ab67 534
Jonathan Austin 1:8aa5cdb4ab67 535 /**
Jonathan Austin 1:8aa5cdb4ab67 536 * Sets the tail to match the head of our circular buffer for transmission,
Jonathan Austin 1:8aa5cdb4ab67 537 * effectively clearing the transmission buffer.
Jonathan Austin 1:8aa5cdb4ab67 538 *
Jonathan Austin 1:8aa5cdb4ab67 539 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 540 * for transmission, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 541 */
Jonathan Austin 1:8aa5cdb4ab67 542 int clearTxBuffer();
Jonathan Austin 1:8aa5cdb4ab67 543
Jonathan Austin 1:8aa5cdb4ab67 544 /**
Jonathan Austin 1:8aa5cdb4ab67 545 * The number of bytes currently stored in our rx buffer waiting to be digested,
Jonathan Austin 1:8aa5cdb4ab67 546 * by the user.
Jonathan Austin 1:8aa5cdb4ab67 547 *
Jonathan Austin 1:8aa5cdb4ab67 548 * @return The currently buffered number of bytes in our rxBuff.
Jonathan Austin 1:8aa5cdb4ab67 549 */
Jonathan Austin 1:8aa5cdb4ab67 550 int rxBufferedSize();
Jonathan Austin 1:8aa5cdb4ab67 551
Jonathan Austin 1:8aa5cdb4ab67 552 /**
Jonathan Austin 1:8aa5cdb4ab67 553 * The number of bytes currently stored in our tx buffer waiting to be transmitted
Jonathan Austin 1:8aa5cdb4ab67 554 * by the hardware.
Jonathan Austin 1:8aa5cdb4ab67 555 *
Jonathan Austin 1:8aa5cdb4ab67 556 * @return The currently buffered number of bytes in our txBuff.
Jonathan Austin 1:8aa5cdb4ab67 557 */
Jonathan Austin 1:8aa5cdb4ab67 558 int txBufferedSize();
Jonathan Austin 1:8aa5cdb4ab67 559
Jonathan Austin 1:8aa5cdb4ab67 560 /**
Jonathan Austin 1:8aa5cdb4ab67 561 * Determines if the serial bus is currently in use by another fiber for reception.
Jonathan Austin 1:8aa5cdb4ab67 562 *
Jonathan Austin 1:8aa5cdb4ab67 563 * @return The state of our mutex lock for reception.
Jonathan Austin 1:8aa5cdb4ab67 564 *
Jonathan Austin 1:8aa5cdb4ab67 565 * @note Only one fiber can call read at a time
Jonathan Austin 1:8aa5cdb4ab67 566 */
Jonathan Austin 1:8aa5cdb4ab67 567 int rxInUse();
Jonathan Austin 1:8aa5cdb4ab67 568
Jonathan Austin 1:8aa5cdb4ab67 569 /**
Jonathan Austin 1:8aa5cdb4ab67 570 * Determines if the serial bus is currently in use by another fiber for transmission.
Jonathan Austin 1:8aa5cdb4ab67 571 *
Jonathan Austin 1:8aa5cdb4ab67 572 * @return The state of our mutex lock for transmition.
Jonathan Austin 1:8aa5cdb4ab67 573 *
Jonathan Austin 1:8aa5cdb4ab67 574 * @note Only one fiber can call send at a time
Jonathan Austin 1:8aa5cdb4ab67 575 */
Jonathan Austin 1:8aa5cdb4ab67 576 int txInUse();
Jonathan Austin 1:8aa5cdb4ab67 577
Jonathan Austin 1:8aa5cdb4ab67 578 /**
Jonathan Austin 1:8aa5cdb4ab67 579 * Detaches a previously configured interrupt
Jonathan Austin 1:8aa5cdb4ab67 580 *
Jonathan Austin 1:8aa5cdb4ab67 581 * @param interruptType one of Serial::RxIrq or Serial::TxIrq
Jonathan Austin 1:8aa5cdb4ab67 582 */
Jonathan Austin 1:8aa5cdb4ab67 583 void detach(Serial::IrqType interuptType);
Jonathan Austin 1:8aa5cdb4ab67 584
Jonathan Austin 1:8aa5cdb4ab67 585 };
Jonathan Austin 1:8aa5cdb4ab67 586
LancasterUniversity 22:23d7b9a4b082 587 #endif