Diff: source/drivers/MicroBitSerial.cpp

Revision:

1:8aa5cdb4ab67

Child:

3:d86a4ddc1867

diff -r fb15f7887843 -r 8aa5cdb4ab67 source/drivers/MicroBitSerial.cpp
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/source/drivers/MicroBitSerial.cpp	Thu Apr 07 01:33:22 2016 +0100
@@ -0,0 +1,1099 @@
+/*
+The MIT License (MIT)
+
+Copyright (c) 2016 British Broadcasting Corporation.
+This software is provided by Lancaster University by arrangement with the BBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+*/
+
+#include "mbed.h"
+#include "MicroBitSerial.h"
+#include "ErrorNo.h"
+#include "MicroBitComponent.h"
+#include "MicroBitFiber.h"
+#include "NotifyEvents.h"
+
+uint8_t MicroBitSerial::status = 0;
+
+int MicroBitSerial::baudrate = 0;
+
+/**
+  * Constructor.
+  * Create an instance of MicroBitSerial
+  *
+  * @param tx the Pin to be used for transmission
+  *
+  * @param rx the Pin to be used for receiving data
+  *
+  * @param rxBufferSize the size of the buffer to be used for receiving bytes
+  *
+  * @param txBufferSize the size of the buffer to be used for transmitting bytes
+  *
+  * @code
+  * MicroBitSerial serial(USBTX, USBRX);
+  * @endcode
+  * @note the default baud rate is 115200. More API details can be found:
+  *       -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/SerialBase.h
+  *       -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/RawSerial.h
+  *
+  *       Buffers aren't allocated until the first send or receive respectively.
+  */
+MicroBitSerial::MicroBitSerial(PinName tx, PinName rx, uint8_t rxBufferSize, uint8_t txBufferSize) : RawSerial(tx,rx), delimeters()
+{
+    this->rxBuffSize = rxBufferSize;
+    this->txBuffSize = txBufferSize;
+
+    this->rxBuff = NULL;
+    this->txBuff = NULL;
+
+    this->rxBuffHead = 0;
+    this->rxBuffTail = 0;
+
+    this->txBuffHead = 0;
+    this->txBuffTail = 0;
+
+    this->rxBuffHeadMatch = -1;
+
+    this->baud(MICROBIT_SERIAL_DEFAULT_BAUD_RATE);
+
+#if CONFIG_ENABLED(MICROBIT_DBG)
+    SERIAL_DEBUG = this;
+#endif
+
+}
+
+/**
+  * An internal interrupt callback for MicroBitSerial configured for when a
+  * character is received.
+  *
+  * Each time a character is received fill our circular buffer!
+  */
+void MicroBitSerial::dataReceived()
+{
+    if(!(status & MICROBIT_SERIAL_RX_BUFF_INIT))
+        return;
+
+    //get the received character
+    char c = getc();
+
+    int delimeterOffset = 0;
+    int delimLength = this->delimeters.length();
+
+    //iterate through our delimeters (if any) to see if there is a match
+    while(delimeterOffset < delimLength)
+    {
+        //fire an event if there is to block any waiting fibers
+        if(this->delimeters.charAt(delimeterOffset) == c)
+            MicroBitEvent(MICROBIT_ID_SERIAL, MICROBIT_SERIAL_EVT_DELIM_MATCH);
+
+        delimeterOffset++;
+    }
+
+    uint16_t newHead = (rxBuffHead + 1) % rxBuffSize;
+
+    //look ahead to our newHead value to see if we are about to collide with the tail
+    if(newHead != rxBuffTail)
+    {
+        //if we are not, store the character, and update our actual head.
+        this->rxBuff[rxBuffHead] = c;
+        rxBuffHead = newHead;
+
+        //if we have any fibers waiting for a specific number of characters, unblock them
+        if(rxBuffHeadMatch >= 0)
+            if(rxBuffHead == rxBuffHeadMatch)
+            {
+                rxBuffHeadMatch = -1;
+                MicroBitEvent(MICROBIT_ID_SERIAL, MICROBIT_SERIAL_EVT_HEAD_MATCH);
+            }
+    }
+    else
+        //otherwise, our buffer is full, send an event to the user...
+        MicroBitEvent(MICROBIT_ID_SERIAL, MICROBIT_SERIAL_EVT_RX_FULL);
+}
+
+/**
+  * An internal interrupt callback for MicroBitSerial.
+  *
+  * Each time the Serial module's buffer is empty, write a character if we have
+  * characters to write.
+  */
+void MicroBitSerial::dataWritten()
+{
+    if(txBuffTail == txBuffHead || !(status & MICROBIT_SERIAL_TX_BUFF_INIT))
+        return;
+
+    //send our current char
+    putc(txBuff[txBuffTail]);
+
+    uint16_t nextTail = (txBuffTail + 1) % txBuffSize;
+
+    //unblock any waiting fibers that are waiting for transmission to finish.
+    if(nextTail == txBuffHead)
+    {
+        MicroBitEvent(MICROBIT_ID_NOTIFY, MICROBIT_SERIAL_EVT_TX_EMPTY);
+        detach(Serial::IrqType::TxIrq);
+    }
+
+    //update our tail!
+    txBuffTail = nextTail;
+}
+
+/**
+  * An internal method to configure an interrupt on tx buffer and also
+  * a best effort copy operation to move bytes from a user buffer to our txBuff
+  *
+  * @param string a pointer to the first character of the users' buffer.
+  *
+  * @param len the length of the string, and ultimately the maximum number of bytes
+  *        that will be copied dependent on the state of txBuff
+  *
+  * @return the number of bytes copied into the buffer.
+  */
+int MicroBitSerial::setTxInterrupt(uint8_t *string, int len)
+{
+    int copiedBytes = 0;
+
+    for(copiedBytes = 0; copiedBytes < len; copiedBytes++)
+    {
+        uint16_t nextHead = (txBuffHead + 1) % txBuffSize;
+        if(nextHead != txBuffTail)
+        {
+            this->txBuff[txBuffHead] = string[copiedBytes];
+            txBuffHead = nextHead;
+        }
+        else
+            break;
+    }
+
+    fiber_wake_on_event(MICROBIT_ID_NOTIFY, MICROBIT_SERIAL_EVT_TX_EMPTY);
+
+    //set the TX interrupt
+    attach(this, &MicroBitSerial::dataWritten, Serial::IrqType::TxIrq);
+
+    return copiedBytes;
+}
+
+/**
+  * Locks the mutex so that others can't use this serial instance for reception
+  */
+void MicroBitSerial::lockRx()
+{
+    status |= MICROBIT_SERIAL_RX_IN_USE;
+}
+
+/**
+  * Locks the mutex so that others can't use this serial instance for transmission
+  */
+void MicroBitSerial::lockTx()
+{
+    status |= MICROBIT_SERIAL_TX_IN_USE;
+}
+
+/**
+  * Unlocks the mutex so that others can use this serial instance for reception
+  */
+void MicroBitSerial::unlockRx()
+{
+    status &= ~MICROBIT_SERIAL_RX_IN_USE;
+}
+
+/**
+  * Unlocks the mutex so that others can use this serial instance for transmission
+  */
+void MicroBitSerial::unlockTx()
+{
+    status &= ~MICROBIT_SERIAL_TX_IN_USE;
+}
+
+/**
+  * We do not want to always have our buffers initialised, especially if users to not
+  * use them. We only bring them up on demand.
+  */
+int MicroBitSerial::initialiseRx()
+{
+    if((status & MICROBIT_SERIAL_RX_BUFF_INIT))
+    {
+        //ensure that we receive no interrupts after freeing our buffer
+        detach(Serial::IrqType::RxIrq);
+        free(this->rxBuff);
+    }
+
+    status &= ~MICROBIT_SERIAL_RX_BUFF_INIT;
+
+    if((this->rxBuff = (uint8_t *)malloc(rxBuffSize)) == NULL)
+        return MICROBIT_NO_RESOURCES;
+
+    this->rxBuffHead = 0;
+    this->rxBuffTail = 0;
+
+    //set the receive interrupt
+    status |= MICROBIT_SERIAL_RX_BUFF_INIT;
+    attach(this, &MicroBitSerial::dataReceived, Serial::IrqType::RxIrq);
+
+    return MICROBIT_OK;
+}
+
+/**
+  * We do not want to always have our buffers initialised, especially if users to not
+  * use them. We only bring them up on demand.
+  */
+int MicroBitSerial::initialiseTx()
+{
+    if((status & MICROBIT_SERIAL_TX_BUFF_INIT))
+    {
+        //ensure that we receive no interrupts after freeing our buffer
+        detach(Serial::IrqType::TxIrq);
+        free(this->txBuff);
+    }
+
+    status &= ~MICROBIT_SERIAL_TX_BUFF_INIT;
+
+    if((this->txBuff = (uint8_t *)malloc(txBuffSize)) == NULL)
+        return MICROBIT_NO_RESOURCES;
+
+    this->txBuffHead = 0;
+    this->txBuffTail = 0;
+
+    status |= MICROBIT_SERIAL_TX_BUFF_INIT;
+
+    return MICROBIT_OK;
+}
+
+/**
+  * An internal method that either spin waits if mode is set to SYNC_SPINWAIT
+  * or puts the fiber to sleep if the mode is set to SYNC_SLEEP
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP
+  */
+void MicroBitSerial::send(MicroBitSerialMode mode)
+{
+    if(mode == SYNC_SPINWAIT)
+        while(txBufferedSize() > 0);
+
+    if(mode == SYNC_SLEEP)
+        fiber_sleep(0);
+}
+
+/**
+  * Reads a single character from the rxBuff
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - A character is read from the rxBuff if available, if there
+  *                    are no characters to be read, a value of zero is returned immediately.
+  *
+  *            SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
+  *                            are no characters to be read, this method will spin
+  *                            (lock up the processor) until a character is available.
+  *
+  *            SYNC_SLEEP - A character is read from the rxBuff if available, if there
+  *                         are no characters to be read, the calling fiber sleeps
+  *                         until there is a character available.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return a character from the circular buffer, or MICROBIT_NO_DATA is there
+  *         are no characters in the buffer.
+  */
+int MicroBitSerial::getChar(MicroBitSerialMode mode)
+{
+    if(mode == ASYNC)
+    {
+        if(!isReadable())
+            return MICROBIT_NO_DATA;
+    }
+
+    if(mode == SYNC_SPINWAIT)
+        while(!isReadable());
+
+    if(mode == SYNC_SLEEP)
+    {
+        if(!isReadable())
+            eventAfter(1, mode);
+    }
+
+    char c = rxBuff[rxBuffTail];
+
+    rxBuffTail = (rxBuffTail + 1) % rxBuffSize;
+
+    return c;
+}
+
+/**
+  * An internal method that copies values from a circular buffer to a linear buffer.
+  *
+  * @param circularBuff a pointer to the source circular buffer
+  *
+  * @param circularBuffSize the size of the circular buffer
+  *
+  * @param linearBuff a pointer to the destination linear buffer
+  *
+  * @param tailPosition the tail position in the circular buffer you want to copy from
+  *
+  * @param headPosition the head position in the circular buffer you want to copy to
+  *
+  * @note this method assumes that the linear buffer has the appropriate amount of
+  *       memory to contain the copy operation
+  */
+void MicroBitSerial::circularCopy(uint8_t *circularBuff, uint8_t circularBuffSize, uint8_t *linearBuff, uint16_t tailPosition, uint16_t headPosition)
+{
+    int toBuffIndex = 0;
+
+    while(tailPosition != headPosition)
+    {
+        linearBuff[toBuffIndex++] = circularBuff[tailPosition];
+
+        tailPosition = (tailPosition + 1) % circularBuffSize;
+    }
+}
+
+/**
+  * Sends a single character over the serial line.
+  *
+  * @param c the character to send
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - the character is copied into the txBuff and returns immediately.
+  *
+  *            SYNC_SPINWAIT - the character is copied into the txBuff and this method
+  *                            will spin (lock up the processor) until the character has
+  *                            been sent.
+  *
+  *            SYNC_SLEEP - the character is copied into the txBuff and the fiber sleeps
+  *                         until the character has been sent. This allows other fibers
+  *                         to continue execution.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
+  *         is using the serial instance for transmission.
+  */
+int MicroBitSerial::sendChar(char c, MicroBitSerialMode mode)
+{
+    if(txInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockTx();
+
+    //lazy initialisation of our tx buffer
+    if(!(status & MICROBIT_SERIAL_TX_BUFF_INIT))
+    {
+        int result = initialiseTx();
+
+        if(result != MICROBIT_OK)
+            return result;
+    }
+
+    uint8_t toTransmit[2] =  { c, '\0'};
+
+    int bytesWritten = setTxInterrupt(toTransmit, 1);
+
+    send(mode);
+
+    unlockTx();
+
+    return bytesWritten;
+}
+
+/**
+  * Sends a ManagedString over the serial line.
+  *
+  * @param s the string to send
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - bytes are copied into the txBuff and returns immediately.
+  *
+  *            SYNC_SPINWAIT - bytes are copied into the txBuff and this method
+  *                            will spin (lock up the processor) until all bytes
+  *                            have been sent.
+  *
+  *            SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
+  *                         until all bytes have been sent. This allows other fibers
+  *                         to continue execution.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
+  *         is using the serial instance for transmission.
+  */
+int MicroBitSerial::send(ManagedString s, MicroBitSerialMode mode)
+{
+    return send((uint8_t *)s.toCharArray(), s.length(), mode);
+}
+
+/**
+  * Sends a buffer of known length over the serial line.
+  *
+  * @param buffer a pointer to the first character of the buffer
+  *
+  * @param len the number of bytes that are safely available to read.
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - bytes are copied into the txBuff and returns immediately.
+  *
+  *            SYNC_SPINWAIT - bytes are copied into the txBuff and this method
+  *                            will spin (lock up the processor) until all bytes
+  *                            have been sent.
+  *
+  *            SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
+  *                         until all bytes have been sent. This allows other fibers
+  *                         to continue execution.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
+  *         is using the serial instance for transmission.
+  */
+int MicroBitSerial::send(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode)
+{
+    if(txInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockTx();
+
+    //lazy initialisation of our tx buffer
+    if(!(status & MICROBIT_SERIAL_TX_BUFF_INIT))
+    {
+        int result = initialiseTx();
+
+        if(result != MICROBIT_OK)
+            return result;
+    }
+
+    int bytesWritten = setTxInterrupt(buffer, bufferLen);
+
+    send(mode);
+
+    unlockTx();
+
+    return bytesWritten;
+}
+
+/**
+  * Reads a single character from the rxBuff
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - A character is read from the rxBuff if available, if there
+  *                    are no characters to be read, a value of MICROBIT_NO_DATA is returned immediately.
+  *
+  *            SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
+  *                            are no characters to be read, this method will spin
+  *                            (lock up the processor) until a character is available.
+  *
+  *            SYNC_SLEEP - A character is read from the rxBuff if available, if there
+  *                         are no characters to be read, the calling fiber sleeps
+  *                         until there is a character available.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return a character, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for reception,
+  *         MICROBIT_NO_RESOURCES if buffer allocation did not complete successfully, or MICROBIT_NO_DATA if
+  *         the rx buffer is empty and the mode given is ASYNC.
+  */
+int MicroBitSerial::read(MicroBitSerialMode mode)
+{
+    if(rxInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockRx();
+
+    //lazy initialisation of our buffers
+    if(!(status & MICROBIT_SERIAL_RX_BUFF_INIT))
+    {
+        int result = initialiseRx();
+
+        if(result != MICROBIT_OK)
+            return result;
+    }
+
+    char c = (char)getChar(mode);
+
+    unlockRx();
+
+    return c;
+}
+
+/**
+  * Reads multiple characters from the rxBuff and returns them as a ManagedString
+  *
+  * @param size the number of characters to read.
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - If the desired number of characters are available, this will return
+  *                    a ManagedString with the expected size. Otherwise, it will read however
+  *                    many characters there are available.
+  *
+  *            SYNC_SPINWAIT - If the desired number of characters are available, this will return
+  *                            a ManagedString with the expected size. Otherwise, this method will spin
+  *                            (lock up the processor) until the desired number of characters have been read.
+  *
+  *            SYNC_SLEEP - If the desired number of characters are available, this will return
+  *                         a ManagedString with the expected size. Otherwise, the calling fiber sleeps
+  *                         until the desired number of characters have been read.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return A ManagedString, or an empty ManagedString if an error was encountered during the read.
+  */
+ManagedString MicroBitSerial::read(int size, MicroBitSerialMode mode)
+{
+    uint8_t buff[size + 1] = { 0 };
+
+    int returnedSize = read((uint8_t *)buff, size, mode);
+
+    if(returnedSize <= 0)
+        return ManagedString();
+
+    return ManagedString((char *)buff, returnedSize);
+}
+
+/**
+  * Reads multiple characters from the rxBuff and fills a user buffer.
+  *
+  * @param buffer a pointer to a user allocated buffer.
+  *
+  * @param bufferLen the amount of data that can be safely stored
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - If the desired number of characters are available, this will fill
+  *                    the given buffer. Otherwise, it will fill the buffer with however
+  *                    many characters there are available.
+  *
+  *            SYNC_SPINWAIT - If the desired number of characters are available, this will fill
+  *                            the given buffer. Otherwise, this method will spin (lock up the processor)
+  *                            and fill the buffer until the desired number of characters have been read.
+  *
+  *            SYNC_SLEEP - If the desired number of characters are available, this will fill
+  *                         the given buffer. Otherwise, the calling fiber sleeps
+  *                         until the desired number of characters have been read.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return the number of characters read, or MICROBIT_SERIAL_IN_USE if another fiber
+  *         is using the instance for receiving.
+  */
+int MicroBitSerial::read(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode)
+{
+    if(rxInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockRx();
+
+    //lazy initialisation of our rx buffer
+    if(!(status & MICROBIT_SERIAL_RX_BUFF_INIT))
+    {
+        int result = initialiseRx();
+
+        if(result != MICROBIT_OK)
+            return result;
+    }
+
+    int bufferIndex = 0;
+
+    int temp = 0;
+
+    if(mode == ASYNC)
+    {
+        while((temp = getChar(mode)) != MICROBIT_NO_DATA && bufferIndex < bufferLen)
+        {
+            buffer[bufferIndex] = (char)temp;
+            bufferIndex++;
+        }
+    }
+
+    if(mode == SYNC_SPINWAIT)
+    {
+        while(bufferIndex < bufferLen)
+        {
+            buffer[bufferIndex] = (char)getChar(mode);
+            bufferIndex++;
+        }
+    }
+
+    if(mode == SYNC_SLEEP)
+    {
+        if(bufferLen > rxBufferedSize())
+            eventAfter(bufferLen - rxBufferedSize(), mode);
+
+        while(bufferIndex < bufferLen)
+        {
+            buffer[bufferIndex] = (char)getChar(mode);
+            bufferIndex++;
+        }
+    }
+
+    unlockRx();
+
+    return bufferIndex;
+}
+
+
+/**
+  * Reads until one of the delimeters matches a character in the rxBuff
+  *
+  * @param delimeters a ManagedString containing a sequence of delimeter characters e.g. ManagedString("\r\n")
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - If one of the delimeters matches a character already in the rxBuff
+  *                    this method will return a ManagedString up to the delimeter.
+  *                    Otherwise, it will return an Empty ManagedString.
+  *
+  *            SYNC_SPINWAIT - If one of the delimeters matches a character already in the rxBuff
+  *                            this method will return a ManagedString up to the delimeter.
+  *                            Otherwise, this method will spin (lock up the processor) until a
+  *                            received character matches one of the delimeters.
+  *
+  *            SYNC_SLEEP - If one of the delimeters matches a character already in the rxBuff
+  *                         this method will return a ManagedString up to the delimeter.
+  *                         Otherwise, the calling fiber sleeps until a character matching one
+  *                         of the delimeters is seen.
+  *
+  *         Defaults to SYNC_SLEEP.
+  *
+  * @return A ManagedString containing the characters up to a delimeter, or an Empty ManagedString,
+  *         if another fiber is currently using this instance for reception.
+  *
+  * @note delimeters are matched on a per byte basis.
+  */
+ManagedString MicroBitSerial::readUntil(ManagedString delimeters, MicroBitSerialMode mode)
+{
+
+    if(rxInUse())
+        return ManagedString();
+
+    //lazy initialisation of our rx buffer
+    if(!(status & MICROBIT_SERIAL_RX_BUFF_INIT))
+    {
+        int result = initialiseRx();
+
+        if(result != MICROBIT_OK)
+            return result;
+    }
+
+    lockRx();
+
+    int localTail = rxBuffTail;
+    int preservedTail = rxBuffTail;
+
+    int foundIndex = -1;
+
+    //ASYNC mode just iterates through our stored characters checking for any matches.
+    while(localTail != rxBuffHead && foundIndex  == -1)
+    {
+        //we use localTail to prevent modification of the actual tail.
+        char c = rxBuff[localTail];
+
+        for(int delimeterIterator = 0; delimeterIterator < delimeters.length(); delimeterIterator++)
+            if(delimeters.charAt(delimeterIterator) == c)
+                foundIndex = localTail;
+
+        localTail = (localTail + 1) % rxBuffSize;
+    }
+
+    //if our mode is SYNC_SPINWAIT and we didn't see any matching characters in our buffer
+    //spin until we find a match!
+    if(mode == SYNC_SPINWAIT)
+    {
+        while(foundIndex == -1)
+        {
+            while(localTail == rxBuffHead);
+
+            char c = rxBuff[localTail];
+
+            for(int delimeterIterator = 0; delimeterIterator < delimeters.length(); delimeterIterator++)
+                if(delimeters.charAt(delimeterIterator) == c)
+                    foundIndex = localTail;
+
+            localTail = (localTail + 1) % rxBuffSize;
+        }
+    }
+
+    //if our mode is SYNC_SLEEP, we set up an event to be fired when we see a
+    //matching character.
+    if(mode == SYNC_SLEEP && foundIndex == -1)
+    {
+        eventOn(delimeters, mode);
+
+        foundIndex = rxBuffHead - 1;
+
+        this->delimeters = ManagedString();
+    }
+
+    if(foundIndex >= 0)
+    {
+        //calculate our local buffer size
+        int localBuffSize = (preservedTail > foundIndex) ? (rxBuffSize - preservedTail) + foundIndex : foundIndex - preservedTail;
+
+        uint8_t localBuff[localBuffSize + 1] = { 0 };
+
+        circularCopy(rxBuff, rxBuffSize, localBuff, preservedTail, foundIndex);
+
+        //plus one for the character we listened for...
+        rxBuffTail = (rxBuffTail + localBuffSize + 1) % rxBuffSize;
+
+        unlockRx();
+
+        return ManagedString((char *)localBuff, localBuffSize);
+    }
+
+    unlockRx();
+
+    return ManagedString();
+}
+
+/**
+  * A wrapper around the inherited method "baud" so we can trap the baud rate
+  * as it changes and restore it if redirect() is called.
+  *
+  * @param baudrate the new baudrate. See:
+  *         - https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/targets/hal/TARGET_NORDIC/TARGET_MCU_NRF51822/serial_api.c
+  *        for permitted baud rates.
+  *
+  * @return MICROBIT_INVALID_PARAMETER if baud rate is less than 0, otherwise MICROBIT_OK.
+  *
+  * @note the underlying implementation chooses the first allowable rate at or above that requested.
+  */
+void MicroBitSerial::baud(int baudrate)
+{
+    if(baudrate < 0)
+        return;
+
+    this->baudrate = baudrate;
+
+    RawSerial::baud(baudrate);
+}
+
+/**
+  * A way of dynamically configuring the serial instance to use pins other than USBTX and USBRX.
+  *
+  * @param tx the new transmission pin.
+  *
+  * @param rx the new reception pin.
+  *
+  * @return MICROBIT_SERIAL_IN_USE if another fiber is currently transmitting or receiving, otherwise MICROBIT_OK.
+  */
+int MicroBitSerial::redirect(PinName tx, PinName rx)
+{
+    if(txInUse() || rxInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockTx();
+    lockRx();
+
+    if(txBufferedSize() > 0)
+        detach(Serial::IrqType::TxIrq);
+
+    detach(Serial::IrqType::RxIrq);
+
+    serial_free(&_serial);
+    serial_init(&_serial, tx, rx);
+
+    attach(this, &MicroBitSerial::dataReceived, Serial::IrqType::RxIrq);
+
+    if(txBufferedSize() > 0)
+        attach(this, &MicroBitSerial::dataWritten, Serial::IrqType::TxIrq);
+
+    this->baud(this->baudrate);
+
+    unlockRx();
+    unlockTx();
+
+    return MICROBIT_OK;
+}
+
+/**
+  * Configures an event to be fired after "len" characters.
+  *
+  * @param len the number of characters to wait before triggering the event.
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - Will configure the event and return immediately.
+  *
+  *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
+  *
+  *            SYNC_SLEEP - Will configure the event and block the current fiber until the
+  *                         event is received.
+  *
+  * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
+  */
+int MicroBitSerial::eventAfter(int len, MicroBitSerialMode mode)
+{
+    if(mode == SYNC_SPINWAIT)
+        return MICROBIT_INVALID_PARAMETER;
+
+    //configure our head match...
+    this->rxBuffHeadMatch = (rxBuffHead + len) % rxBuffSize;
+
+    //block!
+    if(mode == SYNC_SLEEP)
+        fiber_wait_for_event(MICROBIT_ID_SERIAL, MICROBIT_SERIAL_EVT_HEAD_MATCH);
+
+    return MICROBIT_OK;
+}
+
+/**
+  * Configures an event to be fired on a match with one of the delimeters.
+  *
+  * @param delimeters the characters to match received characters against e.g. ManagedString("\r\n")
+  *
+  * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
+  *        gives a different behaviour:
+  *
+  *            ASYNC - Will configure the event and return immediately.
+  *
+  *            SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
+  *
+  *            SYNC_SLEEP - Will configure the event and block the current fiber until the
+  *                         event is received.
+  *
+  * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
+  *
+  * @note delimeters are matched on a per byte basis.
+  */
+int MicroBitSerial::eventOn(ManagedString delimeters, MicroBitSerialMode mode)
+{
+    if(mode == SYNC_SPINWAIT)
+        return MICROBIT_INVALID_PARAMETER;
+
+    //configure our head match...
+    this->delimeters = delimeters;
+
+    //block!
+    if(mode == SYNC_SLEEP)
+        fiber_wait_for_event(MICROBIT_ID_SERIAL, MICROBIT_SERIAL_EVT_DELIM_MATCH);
+
+    return MICROBIT_OK;
+}
+
+/**
+  * Determines whether there is any data waiting in our Rx buffer.
+  *
+  * @return 1 if we have space, 0 if we do not.
+  *
+  * @note We do not wrap the super's readable() method as we don't want to
+  *       interfere with communities that use manual calls to serial.readable().
+  */
+int MicroBitSerial::isReadable()
+{
+    return (rxBuffTail != rxBuffHead) ? 1 : 0;
+}
+
+/**
+  * Determines if we have space in our txBuff.
+  *
+  * @return 1 if we have space, 0 if we do not.
+  *
+  * @note We do not wrap the super's writeable() method as we don't want to
+  *       interfere with communities that use manual calls to serial.writeable().
+  */
+int MicroBitSerial::isWriteable()
+{
+    return (txBuffHead != (txBuffTail - 1)) ? 1 : 0;
+}
+
+/**
+  * Reconfigures the size of our rxBuff
+  *
+  * @param size the new size for our rxBuff
+  *
+  * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
+  *         for reception, otherwise MICROBIT_OK.
+  */
+int MicroBitSerial::setRxBufferSize(uint8_t size)
+{
+    if(rxInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockRx();
+
+    this->rxBuffSize = size;
+
+    int result = initialiseRx();
+
+    unlockRx();
+
+    return result;
+}
+
+/**
+  * Reconfigures the size of our txBuff
+  *
+  * @param size the new size for our txBuff
+  *
+  * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
+  *         for transmission, otherwise MICROBIT_OK.
+  */
+int MicroBitSerial::setTxBufferSize(uint8_t size)
+{
+    if(txInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockTx();
+
+    this->txBuffSize = size;
+
+    int result = initialiseTx();
+
+    unlockTx();
+
+    return result;
+}
+
+/**
+  * The size of our rx buffer in bytes.
+  *
+  * @return the current size of rxBuff in bytes
+  */
+int MicroBitSerial::getRxBufferSize()
+{
+    return this->rxBuffSize;
+}
+
+/**
+  * The size of our tx buffer in bytes.
+  *
+  * @return the current size of txBuff in bytes
+  */
+int MicroBitSerial::getTxBufferSize()
+{
+    return this->txBuffSize;
+}
+
+/**
+  * Sets the tail to match the head of our circular buffer for reception,
+  * effectively clearing the reception buffer.
+  *
+  * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
+  *         for reception, otherwise MICROBIT_OK.
+  */
+int MicroBitSerial::clearRxBuffer()
+{
+    if(rxInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockRx();
+
+    rxBuffTail = rxBuffHead;
+
+    unlockRx();
+
+    return MICROBIT_OK;
+}
+
+/**
+  * Sets the tail to match the head of our circular buffer for transmission,
+  * effectively clearing the transmission buffer.
+  *
+  * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
+  *         for transmission, otherwise MICROBIT_OK.
+  */
+int MicroBitSerial::clearTxBuffer()
+{
+    if(txInUse())
+        return MICROBIT_SERIAL_IN_USE;
+
+    lockTx();
+
+    txBuffTail = txBuffHead;
+
+    unlockTx();
+
+    return MICROBIT_OK;
+}
+
+/**
+  * The number of bytes currently stored in our rx buffer waiting to be digested,
+  * by the user.
+  *
+  * @return The currently buffered number of bytes in our rxBuff.
+  */
+int MicroBitSerial::rxBufferedSize()
+{
+    if(rxBuffTail > rxBuffHead)
+        return (rxBuffSize - rxBuffTail) + rxBuffHead;
+
+    return rxBuffHead - rxBuffTail;
+}
+
+/**
+  * The number of bytes currently stored in our tx buffer waiting to be transmitted
+  * by the hardware.
+  *
+  * @return The currently buffered number of bytes in our txBuff.
+  */
+int MicroBitSerial::txBufferedSize()
+{
+    if(txBuffTail > txBuffHead)
+        return (txBuffSize - txBuffTail) + txBuffHead;
+
+    return txBuffHead - txBuffTail;
+}
+
+/**
+  * Determines if the serial bus is currently in use by another fiber for reception.
+  *
+  * @return The state of our mutex lock for reception.
+  *
+  * @note Only one fiber can call read at a time
+  */
+int MicroBitSerial::rxInUse()
+{
+    return (status & MICROBIT_SERIAL_RX_IN_USE);
+}
+
+/**
+  * Determines if the serial bus is currently in use by another fiber for transmission.
+  *
+  * @return The state of our mutex lock for transmition.
+  *
+  * @note Only one fiber can call send at a time
+  */
+int MicroBitSerial::txInUse()
+{
+    return (status & MICROBIT_SERIAL_TX_IN_USE);
+}
+
+/**
+  * Detaches a previously configured interrupt
+  *
+  * @param interruptType one of Serial::RxIrq or Serial::TxIrq
+  */
+void MicroBitSerial::detach(Serial::IrqType interruptType)
+{
+    //we detach by sending a bad value to attach, for some weird reason...
+    attach((MicroBitSerial *)NULL, &MicroBitSerial::dataReceived, interruptType);
+}