Martin Cottrell / microbit-dal

No Changes

Dependencies:   BLE_API mbed-dev-bin nRF51822

Dependents:   microbit

Fork of microbit-dal by Lancaster University

inc/drivers/MicroBitSerial.h@75:ae9a17da71af, 2017-01-13 (annotated)

Committer:
Asimov
Date:
Fri Jan 13 21:14:06 2017 +0000
Revision:
75:ae9a17da71af
Parent:
67:99cfde195ff3 
No Changes

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 *
LancasterUniversity 25:27299423d813 108 * @param mode determines whether to configure the current fiber context or not. If
LancasterUniversity 25:27299423d813 109 * The mode is SYNC_SPINWAIT, the context will not be configured, otherwise
LancasterUniversity 25:27299423d813 110 * no context will be configured.
LancasterUniversity 25:27299423d813 111 *
Jonathan Austin 1:8aa5cdb4ab67 112 * @return the number of bytes copied into the buffer.
Jonathan Austin 1:8aa5cdb4ab67 113 */
LancasterUniversity 25:27299423d813 114 int setTxInterrupt(uint8_t *string, int len, MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 115
Jonathan Austin 1:8aa5cdb4ab67 116 /**
Jonathan Austin 1:8aa5cdb4ab67 117 * Locks the mutex so that others can't use this serial instance for reception
Jonathan Austin 1:8aa5cdb4ab67 118 */
Jonathan Austin 1:8aa5cdb4ab67 119 void lockRx();
Jonathan Austin 1:8aa5cdb4ab67 120
Jonathan Austin 1:8aa5cdb4ab67 121 /**
Jonathan Austin 1:8aa5cdb4ab67 122 * Locks the mutex so that others can't use this serial instance for transmission
Jonathan Austin 1:8aa5cdb4ab67 123 */
Jonathan Austin 1:8aa5cdb4ab67 124 void lockTx();
Jonathan Austin 1:8aa5cdb4ab67 125
Jonathan Austin 1:8aa5cdb4ab67 126 /**
Jonathan Austin 1:8aa5cdb4ab67 127 * Unlocks the mutex so that others can use this serial instance for reception
Jonathan Austin 1:8aa5cdb4ab67 128 */
Jonathan Austin 1:8aa5cdb4ab67 129 void unlockRx();
Jonathan Austin 1:8aa5cdb4ab67 130
Jonathan Austin 1:8aa5cdb4ab67 131 /**
Jonathan Austin 1:8aa5cdb4ab67 132 * Unlocks the mutex so that others can use this serial instance for transmission
Jonathan Austin 1:8aa5cdb4ab67 133 */
Jonathan Austin 1:8aa5cdb4ab67 134 void unlockTx();
Jonathan Austin 1:8aa5cdb4ab67 135
Jonathan Austin 1:8aa5cdb4ab67 136 /**
Jonathan Austin 1:8aa5cdb4ab67 137 * We do not want to always have our buffers initialised, especially if users to not
Jonathan Austin 1:8aa5cdb4ab67 138 * use them. We only bring them up on demand.
Jonathan Austin 1:8aa5cdb4ab67 139 */
Jonathan Austin 1:8aa5cdb4ab67 140 int initialiseRx();
Jonathan Austin 1:8aa5cdb4ab67 141
Jonathan Austin 1:8aa5cdb4ab67 142 /**
Jonathan Austin 1:8aa5cdb4ab67 143 * We do not want to always have our buffers initialised, especially if users to not
Jonathan Austin 1:8aa5cdb4ab67 144 * use them. We only bring them up on demand.
Jonathan Austin 1:8aa5cdb4ab67 145 */
Jonathan Austin 1:8aa5cdb4ab67 146 int initialiseTx();
Jonathan Austin 1:8aa5cdb4ab67 147
Jonathan Austin 1:8aa5cdb4ab67 148 /**
Jonathan Austin 1:8aa5cdb4ab67 149 * An internal method that either spin waits if mode is set to SYNC_SPINWAIT
Jonathan Austin 1:8aa5cdb4ab67 150 * or puts the fiber to sleep if the mode is set to SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 151 *
Jonathan Austin 1:8aa5cdb4ab67 152 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 153 */
Jonathan Austin 1:8aa5cdb4ab67 154 void send(MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 155
Jonathan Austin 1:8aa5cdb4ab67 156 /**
Jonathan Austin 1:8aa5cdb4ab67 157 * Reads a single character from the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 158 *
Jonathan Austin 1:8aa5cdb4ab67 159 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 160 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 161 *
Jonathan Austin 1:8aa5cdb4ab67 162 * ASYNC - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 163 * are no characters to be read, a value of zero is returned immediately.
Jonathan Austin 1:8aa5cdb4ab67 164 *
Jonathan Austin 1:8aa5cdb4ab67 165 * SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 166 * are no characters to be read, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 167 * (lock up the processor) until a character is available.
Jonathan Austin 1:8aa5cdb4ab67 168 *
Jonathan Austin 1:8aa5cdb4ab67 169 * SYNC_SLEEP - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 170 * are no characters to be read, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 171 * until there is a character available.
Jonathan Austin 1:8aa5cdb4ab67 172 *
Jonathan Austin 1:8aa5cdb4ab67 173 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 174 *
Jonathan Austin 1:8aa5cdb4ab67 175 * @return a character from the circular buffer, or MICROBIT_NO_DATA is there
Jonathan Austin 1:8aa5cdb4ab67 176 * are no characters in the buffer.
Jonathan Austin 1:8aa5cdb4ab67 177 */
Jonathan Austin 1:8aa5cdb4ab67 178 int getChar(MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 179
Jonathan Austin 1:8aa5cdb4ab67 180 /**
Jonathan Austin 1:8aa5cdb4ab67 181 * An internal method that copies values from a circular buffer to a linear buffer.
Jonathan Austin 1:8aa5cdb4ab67 182 *
Jonathan Austin 1:8aa5cdb4ab67 183 * @param circularBuff a pointer to the source circular buffer
Jonathan Austin 1:8aa5cdb4ab67 184 *
Jonathan Austin 1:8aa5cdb4ab67 185 * @param circularBuffSize the size of the circular buffer
Jonathan Austin 1:8aa5cdb4ab67 186 *
Jonathan Austin 1:8aa5cdb4ab67 187 * @param linearBuff a pointer to the destination linear buffer
Jonathan Austin 1:8aa5cdb4ab67 188 *
Jonathan Austin 1:8aa5cdb4ab67 189 * @param tailPosition the tail position in the circular buffer you want to copy from
Jonathan Austin 1:8aa5cdb4ab67 190 *
Jonathan Austin 1:8aa5cdb4ab67 191 * @param headPosition the head position in the circular buffer you want to copy to
Jonathan Austin 1:8aa5cdb4ab67 192 *
Jonathan Austin 1:8aa5cdb4ab67 193 * @note this method assumes that the linear buffer has the appropriate amount of
Jonathan Austin 1:8aa5cdb4ab67 194 * memory to contain the copy operation
Jonathan Austin 1:8aa5cdb4ab67 195 */
Jonathan Austin 1:8aa5cdb4ab67 196 void circularCopy(uint8_t *circularBuff, uint8_t circularBuffSize, uint8_t *linearBuff, uint16_t tailPosition, uint16_t headPosition);
Jonathan Austin 1:8aa5cdb4ab67 197
Jonathan Austin 1:8aa5cdb4ab67 198 public:
Jonathan Austin 1:8aa5cdb4ab67 199
Jonathan Austin 1:8aa5cdb4ab67 200 /**
Jonathan Austin 1:8aa5cdb4ab67 201 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 202 * Create an instance of MicroBitSerial
Jonathan Austin 1:8aa5cdb4ab67 203 *
Jonathan Austin 1:8aa5cdb4ab67 204 * @param tx the Pin to be used for transmission
Jonathan Austin 1:8aa5cdb4ab67 205 *
Jonathan Austin 1:8aa5cdb4ab67 206 * @param rx the Pin to be used for receiving data
Jonathan Austin 1:8aa5cdb4ab67 207 *
Jonathan Austin 1:8aa5cdb4ab67 208 * @param rxBufferSize the size of the buffer to be used for receiving bytes
Jonathan Austin 1:8aa5cdb4ab67 209 *
Jonathan Austin 1:8aa5cdb4ab67 210 * @param txBufferSize the size of the buffer to be used for transmitting bytes
Jonathan Austin 1:8aa5cdb4ab67 211 *
Jonathan Austin 1:8aa5cdb4ab67 212 * @code
Jonathan Austin 1:8aa5cdb4ab67 213 * MicroBitSerial serial(USBTX, USBRX);
Jonathan Austin 1:8aa5cdb4ab67 214 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 215 * @note the default baud rate is 115200. More API details can be found:
Jonathan Austin 1:8aa5cdb4ab67 216 * -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/SerialBase.h
Jonathan Austin 1:8aa5cdb4ab67 217 * -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/RawSerial.h
Jonathan Austin 1:8aa5cdb4ab67 218 *
Jonathan Austin 1:8aa5cdb4ab67 219 * Buffers aren't allocated until the first send or receive respectively.
Jonathan Austin 1:8aa5cdb4ab67 220 */
Jonathan Austin 1:8aa5cdb4ab67 221 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 222
Jonathan Austin 1:8aa5cdb4ab67 223 /**
Jonathan Austin 1:8aa5cdb4ab67 224 * Sends a single character over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 225 *
Jonathan Austin 1:8aa5cdb4ab67 226 * @param c the character to send
Jonathan Austin 1:8aa5cdb4ab67 227 *
Jonathan Austin 1:8aa5cdb4ab67 228 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 229 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 230 *
Jonathan Austin 1:8aa5cdb4ab67 231 * ASYNC - the character is copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 232 *
Jonathan Austin 1:8aa5cdb4ab67 233 * SYNC_SPINWAIT - the character is copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 234 * will spin (lock up the processor) until the character has
Jonathan Austin 1:8aa5cdb4ab67 235 * been sent.
Jonathan Austin 1:8aa5cdb4ab67 236 *
Jonathan Austin 1:8aa5cdb4ab67 237 * SYNC_SLEEP - the character is copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 238 * until the character has been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 239 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 240 *
Jonathan Austin 1:8aa5cdb4ab67 241 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 242 *
Jonathan Austin 1:8aa5cdb4ab67 243 * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 244 * is using the serial instance for transmission.
Jonathan Austin 1:8aa5cdb4ab67 245 */
Jonathan Austin 1:8aa5cdb4ab67 246 int sendChar(char c, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 247
Jonathan Austin 1:8aa5cdb4ab67 248 /**
Jonathan Austin 1:8aa5cdb4ab67 249 * Sends a ManagedString over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 250 *
Jonathan Austin 1:8aa5cdb4ab67 251 * @param s the string to send
Jonathan Austin 1:8aa5cdb4ab67 252 *
Jonathan Austin 1:8aa5cdb4ab67 253 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 254 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 255 *
Jonathan Austin 1:8aa5cdb4ab67 256 * ASYNC - bytes are copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 257 *
Jonathan Austin 1:8aa5cdb4ab67 258 * SYNC_SPINWAIT - bytes are copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 259 * will spin (lock up the processor) until all bytes
Jonathan Austin 1:8aa5cdb4ab67 260 * have been sent.
Jonathan Austin 1:8aa5cdb4ab67 261 *
Jonathan Austin 1:8aa5cdb4ab67 262 * SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 263 * until all bytes have been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 264 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 265 *
Jonathan Austin 1:8aa5cdb4ab67 266 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 267 *
LancasterUniversity 67:99cfde195ff3 268 * @return the number of bytes written, MICROBIT_SERIAL_IN_USE if another fiber
LancasterUniversity 67:99cfde195ff3 269 * is using the serial instance for transmission, MICROBIT_INVALID_PARAMETER
LancasterUniversity 67:99cfde195ff3 270 * if buffer is invalid, or the given bufferLen is <= 0.
Jonathan Austin 1:8aa5cdb4ab67 271 */
Jonathan Austin 1:8aa5cdb4ab67 272 int send(ManagedString s, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 273
Jonathan Austin 1:8aa5cdb4ab67 274 /**
Jonathan Austin 1:8aa5cdb4ab67 275 * Sends a buffer of known length over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 276 *
Jonathan Austin 1:8aa5cdb4ab67 277 * @param buffer a pointer to the first character of the buffer
Jonathan Austin 1:8aa5cdb4ab67 278 *
Jonathan Austin 1:8aa5cdb4ab67 279 * @param len the number of bytes that are safely available to read.
Jonathan Austin 1:8aa5cdb4ab67 280 *
Jonathan Austin 1:8aa5cdb4ab67 281 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 282 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 283 *
Jonathan Austin 1:8aa5cdb4ab67 284 * ASYNC - bytes are copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 285 *
Jonathan Austin 1:8aa5cdb4ab67 286 * SYNC_SPINWAIT - bytes are copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 287 * will spin (lock up the processor) until all bytes
Jonathan Austin 1:8aa5cdb4ab67 288 * have been sent.
Jonathan Austin 1:8aa5cdb4ab67 289 *
Jonathan Austin 1:8aa5cdb4ab67 290 * SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 291 * until all bytes have been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 292 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 293 *
Jonathan Austin 1:8aa5cdb4ab67 294 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 295 *
LancasterUniversity 67:99cfde195ff3 296 * @return the number of bytes written, MICROBIT_SERIAL_IN_USE if another fiber
LancasterUniversity 67:99cfde195ff3 297 * is using the serial instance for transmission, MICROBIT_INVALID_PARAMETER
LancasterUniversity 67:99cfde195ff3 298 * if buffer is invalid, or the given bufferLen is <= 0.
Jonathan Austin 1:8aa5cdb4ab67 299 */
Jonathan Austin 1:8aa5cdb4ab67 300 int send(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 301
Jonathan Austin 1:8aa5cdb4ab67 302 /**
Jonathan Austin 1:8aa5cdb4ab67 303 * Reads a single character from the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 304 *
Jonathan Austin 1:8aa5cdb4ab67 305 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 306 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 307 *
Jonathan Austin 1:8aa5cdb4ab67 308 * ASYNC - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 309 * are no characters to be read, a value of MICROBIT_NO_DATA is returned immediately.
Jonathan Austin 1:8aa5cdb4ab67 310 *
Jonathan Austin 1:8aa5cdb4ab67 311 * SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 312 * are no characters to be read, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 313 * (lock up the processor) until a character is available.
Jonathan Austin 1:8aa5cdb4ab67 314 *
Jonathan Austin 1:8aa5cdb4ab67 315 * SYNC_SLEEP - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 316 * are no characters to be read, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 317 * until there is a character available.
Jonathan Austin 1:8aa5cdb4ab67 318 *
Jonathan Austin 1:8aa5cdb4ab67 319 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 320 *
Jonathan Austin 1:8aa5cdb4ab67 321 * @return a character, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for reception,
Jonathan Austin 1:8aa5cdb4ab67 322 * MICROBIT_NO_RESOURCES if buffer allocation did not complete successfully, or MICROBIT_NO_DATA if
Jonathan Austin 1:8aa5cdb4ab67 323 * the rx buffer is empty and the mode given is ASYNC.
Jonathan Austin 1:8aa5cdb4ab67 324 */
Jonathan Austin 1:8aa5cdb4ab67 325 int read(MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 326
Jonathan Austin 1:8aa5cdb4ab67 327 /**
Jonathan Austin 1:8aa5cdb4ab67 328 * Reads multiple characters from the rxBuff and returns them as a ManagedString
Jonathan Austin 1:8aa5cdb4ab67 329 *
Jonathan Austin 1:8aa5cdb4ab67 330 * @param size the number of characters to read.
Jonathan Austin 1:8aa5cdb4ab67 331 *
Jonathan Austin 1:8aa5cdb4ab67 332 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 333 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 334 *
Jonathan Austin 1:8aa5cdb4ab67 335 * ASYNC - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 336 * a ManagedString with the expected size. Otherwise, it will read however
Jonathan Austin 1:8aa5cdb4ab67 337 * many characters there are available.
Jonathan Austin 1:8aa5cdb4ab67 338 *
Jonathan Austin 1:8aa5cdb4ab67 339 * SYNC_SPINWAIT - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 340 * a ManagedString with the expected size. Otherwise, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 341 * (lock up the processor) until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 342 *
Jonathan Austin 1:8aa5cdb4ab67 343 * SYNC_SLEEP - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 344 * a ManagedString with the expected size. Otherwise, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 345 * until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 346 *
Jonathan Austin 1:8aa5cdb4ab67 347 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 348 *
Jonathan Austin 1:8aa5cdb4ab67 349 * @return A ManagedString, or an empty ManagedString if an error was encountered during the read.
Jonathan Austin 1:8aa5cdb4ab67 350 */
Jonathan Austin 1:8aa5cdb4ab67 351 ManagedString read(int size, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 352
Jonathan Austin 1:8aa5cdb4ab67 353 /**
Jonathan Austin 1:8aa5cdb4ab67 354 * Reads multiple characters from the rxBuff and fills a user buffer.
Jonathan Austin 1:8aa5cdb4ab67 355 *
Jonathan Austin 1:8aa5cdb4ab67 356 * @param buffer a pointer to a user allocated buffer.
Jonathan Austin 1:8aa5cdb4ab67 357 *
Jonathan Austin 1:8aa5cdb4ab67 358 * @param bufferLen the amount of data that can be safely stored
Jonathan Austin 1:8aa5cdb4ab67 359 *
Jonathan Austin 1:8aa5cdb4ab67 360 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 361 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 362 *
Jonathan Austin 1:8aa5cdb4ab67 363 * ASYNC - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 364 * the given buffer. Otherwise, it will fill the buffer with however
Jonathan Austin 1:8aa5cdb4ab67 365 * many characters there are available.
Jonathan Austin 1:8aa5cdb4ab67 366 *
Jonathan Austin 1:8aa5cdb4ab67 367 * SYNC_SPINWAIT - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 368 * the given buffer. Otherwise, this method will spin (lock up the processor)
Jonathan Austin 1:8aa5cdb4ab67 369 * and fill the buffer until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 370 *
Jonathan Austin 1:8aa5cdb4ab67 371 * SYNC_SLEEP - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 372 * the given buffer. Otherwise, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 373 * until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 374 *
Jonathan Austin 1:8aa5cdb4ab67 375 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 376 *
Jonathan Austin 1:8aa5cdb4ab67 377 * @return the number of characters read, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 378 * is using the instance for receiving.
Jonathan Austin 1:8aa5cdb4ab67 379 */
Jonathan Austin 1:8aa5cdb4ab67 380 int read(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 381
Jonathan Austin 1:8aa5cdb4ab67 382 /**
Jonathan Austin 1:8aa5cdb4ab67 383 * Reads until one of the delimeters matches a character in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 384 *
Jonathan Austin 1:8aa5cdb4ab67 385 * @param delimeters a ManagedString containing a sequence of delimeter characters e.g. ManagedString("\r\n")
Jonathan Austin 1:8aa5cdb4ab67 386 *
Jonathan Austin 1:8aa5cdb4ab67 387 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 388 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 389 *
Jonathan Austin 1:8aa5cdb4ab67 390 * ASYNC - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 391 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 392 * Otherwise, it will return an Empty ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 393 *
Jonathan Austin 1:8aa5cdb4ab67 394 * SYNC_SPINWAIT - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 395 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 396 * Otherwise, this method will spin (lock up the processor) until a
Jonathan Austin 1:8aa5cdb4ab67 397 * received character matches one of the delimeters.
Jonathan Austin 1:8aa5cdb4ab67 398 *
Jonathan Austin 1:8aa5cdb4ab67 399 * SYNC_SLEEP - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 400 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 401 * Otherwise, the calling fiber sleeps until a character matching one
Jonathan Austin 1:8aa5cdb4ab67 402 * of the delimeters is seen.
Jonathan Austin 1:8aa5cdb4ab67 403 *
Jonathan Austin 1:8aa5cdb4ab67 404 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 405 *
Jonathan Austin 1:8aa5cdb4ab67 406 * @return A ManagedString containing the characters up to a delimeter, or an Empty ManagedString,
Jonathan Austin 1:8aa5cdb4ab67 407 * if another fiber is currently using this instance for reception.
Jonathan Austin 1:8aa5cdb4ab67 408 *
Jonathan Austin 1:8aa5cdb4ab67 409 * @note delimeters are matched on a per byte basis.
Jonathan Austin 1:8aa5cdb4ab67 410 */
Jonathan Austin 1:8aa5cdb4ab67 411 ManagedString readUntil(ManagedString delimeters, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 412
Jonathan Austin 1:8aa5cdb4ab67 413 /**
Jonathan Austin 1:8aa5cdb4ab67 414 * A wrapper around the inherited method "baud" so we can trap the baud rate
Jonathan Austin 1:8aa5cdb4ab67 415 * as it changes and restore it if redirect() is called.
Jonathan Austin 1:8aa5cdb4ab67 416 *
Jonathan Austin 1:8aa5cdb4ab67 417 * @param baudrate the new baudrate. See:
Jonathan Austin 1:8aa5cdb4ab67 418 * - https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/targets/hal/TARGET_NORDIC/TARGET_MCU_NRF51822/serial_api.c
Jonathan Austin 1:8aa5cdb4ab67 419 * for permitted baud rates.
Jonathan Austin 1:8aa5cdb4ab67 420 *
Jonathan Austin 1:8aa5cdb4ab67 421 * @return MICROBIT_INVALID_PARAMETER if baud rate is less than 0, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 422 *
Jonathan Austin 1:8aa5cdb4ab67 423 * @note the underlying implementation chooses the first allowable rate at or above that requested.
Jonathan Austin 1:8aa5cdb4ab67 424 */
Jonathan Austin 1:8aa5cdb4ab67 425 void baud(int baudrate);
Jonathan Austin 1:8aa5cdb4ab67 426
Jonathan Austin 1:8aa5cdb4ab67 427 /**
Jonathan Austin 1:8aa5cdb4ab67 428 * A way of dynamically configuring the serial instance to use pins other than USBTX and USBRX.
Jonathan Austin 1:8aa5cdb4ab67 429 *
Jonathan Austin 1:8aa5cdb4ab67 430 * @param tx the new transmission pin.
Jonathan Austin 1:8aa5cdb4ab67 431 *
Jonathan Austin 1:8aa5cdb4ab67 432 * @param rx the new reception pin.
Jonathan Austin 1:8aa5cdb4ab67 433 *
Jonathan Austin 1:8aa5cdb4ab67 434 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently transmitting or receiving, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 435 */
Jonathan Austin 1:8aa5cdb4ab67 436 int redirect(PinName tx, PinName rx);
Jonathan Austin 1:8aa5cdb4ab67 437
Jonathan Austin 1:8aa5cdb4ab67 438 /**
Jonathan Austin 1:8aa5cdb4ab67 439 * Configures an event to be fired after "len" characters.
Jonathan Austin 1:8aa5cdb4ab67 440 *
LancasterUniversity 66:2fc7d7c2fffc 441 * Will generate an event with the ID: MICROBIT_ID_SERIAL and the value MICROBIT_SERIAL_EVT_HEAD_MATCH.
LancasterUniversity 66:2fc7d7c2fffc 442 *
Jonathan Austin 1:8aa5cdb4ab67 443 * @param len the number of characters to wait before triggering the event.
Jonathan Austin 1:8aa5cdb4ab67 444 *
Jonathan Austin 1:8aa5cdb4ab67 445 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 446 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 447 *
Jonathan Austin 1:8aa5cdb4ab67 448 * ASYNC - Will configure the event and return immediately.
Jonathan Austin 1:8aa5cdb4ab67 449 *
Jonathan Austin 1:8aa5cdb4ab67 450 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
Jonathan Austin 1:8aa5cdb4ab67 451 *
Jonathan Austin 1:8aa5cdb4ab67 452 * SYNC_SLEEP - Will configure the event and block the current fiber until the
Jonathan Austin 1:8aa5cdb4ab67 453 * event is received.
Jonathan Austin 1:8aa5cdb4ab67 454 *
Jonathan Austin 1:8aa5cdb4ab67 455 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 456 */
Jonathan Austin 1:8aa5cdb4ab67 457 int eventAfter(int len, MicroBitSerialMode mode = ASYNC);
Jonathan Austin 1:8aa5cdb4ab67 458
Jonathan Austin 1:8aa5cdb4ab67 459 /**
Jonathan Austin 1:8aa5cdb4ab67 460 * Configures an event to be fired on a match with one of the delimeters.
Jonathan Austin 1:8aa5cdb4ab67 461 *
LancasterUniversity 66:2fc7d7c2fffc 462 * Will generate an event with the ID: MICROBIT_ID_SERIAL and the value MICROBIT_SERIAL_EVT_DELIM_MATCH.
LancasterUniversity 66:2fc7d7c2fffc 463 *
LancasterUniversity 66:2fc7d7c2fffc 464 * @param delimeters the characters to match received characters against e.g. ManagedString("\n")
Jonathan Austin 1:8aa5cdb4ab67 465 *
Jonathan Austin 1:8aa5cdb4ab67 466 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 467 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 468 *
Jonathan Austin 1:8aa5cdb4ab67 469 * ASYNC - Will configure the event and return immediately.
Jonathan Austin 1:8aa5cdb4ab67 470 *
Jonathan Austin 1:8aa5cdb4ab67 471 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
Jonathan Austin 1:8aa5cdb4ab67 472 *
Jonathan Austin 1:8aa5cdb4ab67 473 * SYNC_SLEEP - Will configure the event and block the current fiber until the
Jonathan Austin 1:8aa5cdb4ab67 474 * event is received.
Jonathan Austin 1:8aa5cdb4ab67 475 *
Jonathan Austin 1:8aa5cdb4ab67 476 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 477 *
Jonathan Austin 1:8aa5cdb4ab67 478 * @note delimeters are matched on a per byte basis.
Jonathan Austin 1:8aa5cdb4ab67 479 */
Jonathan Austin 1:8aa5cdb4ab67 480 int eventOn(ManagedString delimeters, MicroBitSerialMode mode = ASYNC);
Jonathan Austin 1:8aa5cdb4ab67 481
Jonathan Austin 1:8aa5cdb4ab67 482 /**
Jonathan Austin 1:8aa5cdb4ab67 483 * Determines whether there is any data waiting in our Rx buffer.
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 readable() method as we don't want to
Jonathan Austin 1:8aa5cdb4ab67 488 * interfere with communities that use manual calls to serial.readable().
Jonathan Austin 1:8aa5cdb4ab67 489 */
Jonathan Austin 1:8aa5cdb4ab67 490 int isReadable();
Jonathan Austin 1:8aa5cdb4ab67 491
Jonathan Austin 1:8aa5cdb4ab67 492 /**
Jonathan Austin 1:8aa5cdb4ab67 493 * Determines if we have space in our txBuff.
Jonathan Austin 1:8aa5cdb4ab67 494 *
Jonathan Austin 1:8aa5cdb4ab67 495 * @return 1 if we have space, 0 if we do not.
Jonathan Austin 1:8aa5cdb4ab67 496 *
Jonathan Austin 1:8aa5cdb4ab67 497 * @note We do not wrap the super's writeable() method as we don't want to
Jonathan Austin 1:8aa5cdb4ab67 498 * interfere with communities that use manual calls to serial.writeable().
Jonathan Austin 1:8aa5cdb4ab67 499 */
Jonathan Austin 1:8aa5cdb4ab67 500 int isWriteable();
Jonathan Austin 1:8aa5cdb4ab67 501
Jonathan Austin 1:8aa5cdb4ab67 502 /**
Jonathan Austin 1:8aa5cdb4ab67 503 * Reconfigures the size of our rxBuff
Jonathan Austin 1:8aa5cdb4ab67 504 *
Jonathan Austin 1:8aa5cdb4ab67 505 * @param size the new size for our rxBuff
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 reception, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 509 */
Jonathan Austin 1:8aa5cdb4ab67 510 int setRxBufferSize(uint8_t size);
Jonathan Austin 1:8aa5cdb4ab67 511
Jonathan Austin 1:8aa5cdb4ab67 512 /**
Jonathan Austin 1:8aa5cdb4ab67 513 * Reconfigures the size of our txBuff
Jonathan Austin 1:8aa5cdb4ab67 514 *
Jonathan Austin 1:8aa5cdb4ab67 515 * @param size the new size for our txBuff
Jonathan Austin 1:8aa5cdb4ab67 516 *
Jonathan Austin 1:8aa5cdb4ab67 517 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 518 * for transmission, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 519 */
Jonathan Austin 1:8aa5cdb4ab67 520 int setTxBufferSize(uint8_t size);
Jonathan Austin 1:8aa5cdb4ab67 521
Jonathan Austin 1:8aa5cdb4ab67 522 /**
Jonathan Austin 1:8aa5cdb4ab67 523 * The size of our rx buffer in bytes.
Jonathan Austin 1:8aa5cdb4ab67 524 *
Jonathan Austin 1:8aa5cdb4ab67 525 * @return the current size of rxBuff in bytes
Jonathan Austin 1:8aa5cdb4ab67 526 */
Jonathan Austin 1:8aa5cdb4ab67 527 int getRxBufferSize();
Jonathan Austin 1:8aa5cdb4ab67 528
Jonathan Austin 1:8aa5cdb4ab67 529 /**
Jonathan Austin 1:8aa5cdb4ab67 530 * The size of our tx buffer in bytes.
Jonathan Austin 1:8aa5cdb4ab67 531 *
Jonathan Austin 1:8aa5cdb4ab67 532 * @return the current size of txBuff in bytes
Jonathan Austin 1:8aa5cdb4ab67 533 */
Jonathan Austin 1:8aa5cdb4ab67 534 int getTxBufferSize();
Jonathan Austin 1:8aa5cdb4ab67 535
Jonathan Austin 1:8aa5cdb4ab67 536 /**
Jonathan Austin 1:8aa5cdb4ab67 537 * Sets the tail to match the head of our circular buffer for reception,
Jonathan Austin 1:8aa5cdb4ab67 538 * effectively clearing the reception buffer.
Jonathan Austin 1:8aa5cdb4ab67 539 *
Jonathan Austin 1:8aa5cdb4ab67 540 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 541 * for reception, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 542 */
Jonathan Austin 1:8aa5cdb4ab67 543 int clearRxBuffer();
Jonathan Austin 1:8aa5cdb4ab67 544
Jonathan Austin 1:8aa5cdb4ab67 545 /**
Jonathan Austin 1:8aa5cdb4ab67 546 * Sets the tail to match the head of our circular buffer for transmission,
Jonathan Austin 1:8aa5cdb4ab67 547 * effectively clearing the transmission buffer.
Jonathan Austin 1:8aa5cdb4ab67 548 *
Jonathan Austin 1:8aa5cdb4ab67 549 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 550 * for transmission, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 551 */
Jonathan Austin 1:8aa5cdb4ab67 552 int clearTxBuffer();
Jonathan Austin 1:8aa5cdb4ab67 553
Jonathan Austin 1:8aa5cdb4ab67 554 /**
Jonathan Austin 1:8aa5cdb4ab67 555 * The number of bytes currently stored in our rx buffer waiting to be digested,
Jonathan Austin 1:8aa5cdb4ab67 556 * by the user.
Jonathan Austin 1:8aa5cdb4ab67 557 *
Jonathan Austin 1:8aa5cdb4ab67 558 * @return The currently buffered number of bytes in our rxBuff.
Jonathan Austin 1:8aa5cdb4ab67 559 */
Jonathan Austin 1:8aa5cdb4ab67 560 int rxBufferedSize();
Jonathan Austin 1:8aa5cdb4ab67 561
Jonathan Austin 1:8aa5cdb4ab67 562 /**
Jonathan Austin 1:8aa5cdb4ab67 563 * The number of bytes currently stored in our tx buffer waiting to be transmitted
Jonathan Austin 1:8aa5cdb4ab67 564 * by the hardware.
Jonathan Austin 1:8aa5cdb4ab67 565 *
Jonathan Austin 1:8aa5cdb4ab67 566 * @return The currently buffered number of bytes in our txBuff.
Jonathan Austin 1:8aa5cdb4ab67 567 */
Jonathan Austin 1:8aa5cdb4ab67 568 int txBufferedSize();
Jonathan Austin 1:8aa5cdb4ab67 569
Jonathan Austin 1:8aa5cdb4ab67 570 /**
Jonathan Austin 1:8aa5cdb4ab67 571 * Determines if the serial bus is currently in use by another fiber for reception.
Jonathan Austin 1:8aa5cdb4ab67 572 *
Jonathan Austin 1:8aa5cdb4ab67 573 * @return The state of our mutex lock for reception.
Jonathan Austin 1:8aa5cdb4ab67 574 *
Jonathan Austin 1:8aa5cdb4ab67 575 * @note Only one fiber can call read at a time
Jonathan Austin 1:8aa5cdb4ab67 576 */
Jonathan Austin 1:8aa5cdb4ab67 577 int rxInUse();
Jonathan Austin 1:8aa5cdb4ab67 578
Jonathan Austin 1:8aa5cdb4ab67 579 /**
Jonathan Austin 1:8aa5cdb4ab67 580 * Determines if the serial bus is currently in use by another fiber for transmission.
Jonathan Austin 1:8aa5cdb4ab67 581 *
Jonathan Austin 1:8aa5cdb4ab67 582 * @return The state of our mutex lock for transmition.
Jonathan Austin 1:8aa5cdb4ab67 583 *
Jonathan Austin 1:8aa5cdb4ab67 584 * @note Only one fiber can call send at a time
Jonathan Austin 1:8aa5cdb4ab67 585 */
Jonathan Austin 1:8aa5cdb4ab67 586 int txInUse();
Jonathan Austin 1:8aa5cdb4ab67 587
Jonathan Austin 1:8aa5cdb4ab67 588 /**
Jonathan Austin 1:8aa5cdb4ab67 589 * Detaches a previously configured interrupt
Jonathan Austin 1:8aa5cdb4ab67 590 *
Jonathan Austin 1:8aa5cdb4ab67 591 * @param interruptType one of Serial::RxIrq or Serial::TxIrq
Jonathan Austin 1:8aa5cdb4ab67 592 */
Jonathan Austin 1:8aa5cdb4ab67 593 void detach(Serial::IrqType interuptType);
Jonathan Austin 1:8aa5cdb4ab67 594
Jonathan Austin 1:8aa5cdb4ab67 595 };
Jonathan Austin 1:8aa5cdb4ab67 596
LancasterUniversity 22:23d7b9a4b082 597 #endif