uBit.serial

Overview

Serial communication provides a simple way to exchange a series of bytes between one computer and another. The runtime’s implementation of serial is general purpose and supports a number of different modes. It has a circular buffer for both the reception and transmission of data, and provides notifications to the user through the MessageBus.

By default, the baud rate for MicroBitSerial is 115200 and has very little overhead up until it is used to send() or read(), at which point buffers are allocated in order to accommodate incoming or outgoing data.

MicroBitSerial inherits from mbeds’ RawSerial class, which exposes a lightweight version of printf() and incurs minimal overhead as MicroBitSerial’s buffers will not be allocated.

The MicroBitSerial class supports multithreaded operation, ensuring that only one fiber can access the Serial port at a time.

The USB interface on the micro:bit is the KL26Z.

Note

On Mac OSX and Linux Serial communication works out of the box, however on Windows an additional driver is required.

Warning

The baud rate is shared across all instances of MicroBitSerial (this is enforced in hardware).

Serial modes

There are three modes of operation for all send() or read() calls:

• ASYNC - Returns immediately after fetching any available data for a given call
• SYNC_SPINWAIT - Synchronously access the serial port until the selected operation is complete. This mode will lock up the processor, and isn’t recommended if multiple fibers are in use.
• SYNC_SLEEP - Blocks the current fiber until the selected operation is complete. This mode cooperates with the Fiber scheduler, and should be used in a multi-fiber program.

Serial debug

In MicroBitConfig.h, the configuration option MICROBIT_DEBUG can be used to activate serial debugging for many of the components in the runtime.

Message Bus ID

Constant	Value
MICROBIT_ID_SERIAL	32

Message Bus Events

Constant	Value
MICROBIT_SERIAL_EVT_DELIM_MATCH	1
MICROBIT_SERIAL_EVT_HEAD_MATCH	2
MICROBIT_SERIAL_EVT_RX_FULL	3

Notify Events

These events use the notification channel MICROBIT_ID_NOTIFY, which provides general purpose synchronisation.

Constant	Value
MICROBIT_SERIAL_EVT_TX_EMPTY	2

API

Constructor

MicroBitSerial(

PinName

tx,

PinName

rx)

Description

Constructor. Create an instance of MicroBitSerial

Parameters

PinName

tx - the Pin to be used for transmission

PinName

rx - the Pin to be used for receiving data

Example

 MicroBitSerial serial(USBTX, USBRX); 

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

MicroBitSerial(

PinName

tx,

PinName

rx,

uint8_t

rxBufferSize)

Description

Constructor. Create an instance of MicroBitSerial

Parameters

PinName

tx - the Pin to be used for transmission

PinName

rx - the Pin to be used for receiving data

uint8_t

rxBufferSize - the size of the buffer to be used for receiving bytes

Example

 MicroBitSerial serial(USBTX, USBRX); 

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

MicroBitSerial(

PinName

tx,

PinName

rx,

uint8_t

rxBufferSize,

uint8_t

txBufferSize)

Description

Constructor. Create an instance of MicroBitSerial

Parameters

PinName

tx - the Pin to be used for transmission

PinName

rx - the Pin to be used for receiving data

uint8_t

rxBufferSize - the size of the buffer to be used for receiving bytes

uint8_t

txBufferSize - the size of the buffer to be used for transmitting bytes

Example

 MicroBitSerial serial(USBTX, USBRX); 

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

sendChar

int

sendChar

(

char

c)

Description

Sends a single character over the serial line.

c

the character to send

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.

Parameters

char

c - the character to send

Returns

the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for transmission.

int

sendChar

(

char

c,

MicroBitSerialMode

mode)

Description

Sends a single character over the serial line.

c

the character to send

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.

Parameters

char

c - the character to send

MicroBitSerialMode

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.

Returns

the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for transmission.

send

int

send

(

ManagedString

s)

Description

Sends a ManagedString over the serial line.

s

the string to send

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.

Parameters

ManagedString

s - the string to send

Returns

the number of bytes written, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for transmission, MICROBIT_INVALID_PARAMETER if buffer is invalid, or the given bufferLen is <= 0.

int

send

(

ManagedString

s,

MicroBitSerialMode

mode)

Description

Sends a ManagedString over the serial line.

s

the string to send

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.

Parameters

ManagedString

s - the string to send

MicroBitSerialMode

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.

Returns

the number of bytes written, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for transmission, MICROBIT_INVALID_PARAMETER if buffer is invalid, or the given bufferLen is <= 0.

int

send

(

uint8_t *

buffer,

int

bufferLen)

Description

Sends a buffer of known length over the serial line.

buffer

a pointer to the first character of the buffer

len

the number of bytes that are safely available to read.

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.

Parameters

uint8_t *

buffer - a pointer to the first character of the buffer

int

bufferLen - a pointer to the first character of the buffer

Returns

the number of bytes written, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for transmission, MICROBIT_INVALID_PARAMETER if buffer is invalid, or the given bufferLen is <= 0.

int

send

(

uint8_t *

buffer,

int

bufferLen,

MicroBitSerialMode

mode)

Description

Sends a buffer of known length over the serial line.

buffer

a pointer to the first character of the buffer

len

the number of bytes that are safely available to read.

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.

Parameters

uint8_t *

buffer - a pointer to the first character of the buffer

int

bufferLen - a pointer to the first character of the buffer

MicroBitSerialMode

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.

Returns

the number of bytes written, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for transmission, MICROBIT_INVALID_PARAMETER if buffer is invalid, or the given bufferLen is <= 0.

read

int

read

()

Description

Reads a single character from the rxBuff

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.

Returns

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

read

(

MicroBitSerialMode

mode)

Description

Reads a single character from the rxBuff

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.

Parameters

MicroBitSerialMode

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.

Returns

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.

ManagedString

read

(

int

size)

Description

Reads multiple characters from the rxBuff and returns them as a ManagedString

size

the number of characters to read.

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.

Parameters

int

size - the number of characters to read.

Returns

A ManagedString , or an empty ManagedString if an error was encountered during the read.

ManagedString

read

(

int

size,

MicroBitSerialMode

mode)

Description

Reads multiple characters from the rxBuff and returns them as a ManagedString

size

the number of characters to read.

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.

Parameters

int

size - the number of characters to read.

MicroBitSerialMode

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.

Returns

A ManagedString , or an empty ManagedString if an error was encountered during the read.

int

read

(

uint8_t *

buffer,

int

bufferLen)

Description

Reads multiple characters from the rxBuff and fills a user buffer.

buffer

a pointer to a user allocated buffer.

bufferLen

the amount of data that can be safely stored

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.

Parameters

uint8_t *

buffer - a pointer to a user allocated buffer.

int

bufferLen - the amount of data that can be safely stored

Returns

the number of characters read, or MICROBIT_SERIAL_IN_USE if another fiber is using the instance for receiving.

int

read

(

uint8_t *

buffer,

int

bufferLen,

MicroBitSerialMode

mode)

Description

Reads multiple characters from the rxBuff and fills a user buffer.

buffer

a pointer to a user allocated buffer.

bufferLen

the amount of data that can be safely stored

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.

Parameters

uint8_t *

buffer - a pointer to a user allocated buffer.

int

bufferLen - the amount of data that can be safely stored

MicroBitSerialMode

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.

Returns

the number of characters read, or MICROBIT_SERIAL_IN_USE if another fiber is using the instance for receiving.

readUntil

ManagedString

readUntil

(

ManagedString

delimeters)

Description

Reads until one of the delimeters matches a character in the rxBuff

delimeters

a ManagedString containing a sequence of delimeter characters e.g. ManagedString (“\r\n”)

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.

Parameters

ManagedString

delimeters - a ManagedString containing a sequence of delimeter characters e.g. ManagedString (“\r\n”)

Returns

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

readUntil

(

ManagedString

delimeters,

MicroBitSerialMode

mode)

Description

Reads until one of the delimeters matches a character in the rxBuff

delimeters

a ManagedString containing a sequence of delimeter characters e.g. ManagedString (“\r\n”)

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.

Parameters

ManagedString

delimeters - a ManagedString containing a sequence of delimeter characters e.g. ManagedString (“\r\n”)

MicroBitSerialMode

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.

Returns

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.

baud

void

baud

(

int

baudrate)

Description

A wrapper around the inherited method “baud” so we can trap the baud rate as it changes and restore it if redirect() is called.

Parameters

int

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.

Returns

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.

redirect

int

redirect

(

PinName

tx,

PinName

rx)

Description

A way of dynamically configuring the serial instance to use pins other than USBTX and USBRX.

Parameters

PinName

tx - the new transmission pin.

PinName

rx - the new reception pin.

Returns

MICROBIT_SERIAL_IN_USE if another fiber is currently transmitting or receiving, otherwise MICROBIT_OK.

eventAfter

int

eventAfter

(

int

len)

Description

Configures an event to be fired after “len” characters.

Will generate an event with the ID: MICROBIT_ID_SERIAL and the value MICROBIT_SERIAL_EVT_HEAD_MATCH.

Parameters

int

len - the number of characters to wait before triggering the event.

Returns

MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.

int

eventAfter

(

int

len,

MicroBitSerialMode

mode)

Description

Configures an event to be fired after “len” characters.

Will generate an event with the ID: MICROBIT_ID_SERIAL and the value MICROBIT_SERIAL_EVT_HEAD_MATCH.

Parameters

int

len - the number of characters to wait before triggering the event.

MicroBitSerialMode

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.

Returns

MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.

eventOn

int

eventOn

(

ManagedString

delimeters)

Description

Configures an event to be fired on a match with one of the delimeters.

Will generate an event with the ID: MICROBIT_ID_SERIAL and the value MICROBIT_SERIAL_EVT_DELIM_MATCH.

Parameters

ManagedString

delimeters - the characters to match received characters against e.g. ManagedString (“\n”)

Returns

MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.

Note

delimeters are matched on a per byte basis.

int

eventOn

(

ManagedString

delimeters,

MicroBitSerialMode

mode)

Description

Configures an event to be fired on a match with one of the delimeters.

Will generate an event with the ID: MICROBIT_ID_SERIAL and the value MICROBIT_SERIAL_EVT_DELIM_MATCH.

Parameters

ManagedString

delimeters - the characters to match received characters against e.g. ManagedString (“\n”)

MicroBitSerialMode

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.

Returns

MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.

Note

delimeters are matched on a per byte basis.

isReadable

int

isReadable

()

Description

Determines whether there is any data waiting in our Rx buffer.

Returns

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().

isWriteable

int

isWriteable

()

Description

Determines if we have space in our txBuff.

Returns

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().

setRxBufferSize

int

setRxBufferSize

(

uint8_t

size)

Description

Reconfigures the size of our rxBuff

Parameters

uint8_t

size - the new size for our rxBuff

Returns

MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance for reception, otherwise MICROBIT_OK.

setTxBufferSize

int

setTxBufferSize

(

uint8_t

size)

Description

Reconfigures the size of our txBuff

Parameters

uint8_t

size - the new size for our txBuff

Returns

MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance for transmission, otherwise MICROBIT_OK.

getRxBufferSize

int

getRxBufferSize

()

Description

The size of our rx buffer in bytes.

Returns

the current size of rxBuff in bytes

getTxBufferSize

int

getTxBufferSize

()

Description

The size of our tx buffer in bytes.

Returns

the current size of txBuff in bytes

clearRxBuffer

int

clearRxBuffer

()

Description

Sets the tail to match the head of our circular buffer for reception, effectively clearing the reception buffer.

Returns

MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance for reception, otherwise MICROBIT_OK.

clearTxBuffer

int

clearTxBuffer

()

Description

Sets the tail to match the head of our circular buffer for transmission, effectively clearing the transmission buffer.

Returns

MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance for transmission, otherwise MICROBIT_OK.

rxBufferedSize

int

rxBufferedSize

()

Description

The number of bytes currently stored in our rx buffer waiting to be digested, by the user.

Returns

The currently buffered number of bytes in our rxBuff.

txBufferedSize

int

txBufferedSize

()

Description

The number of bytes currently stored in our tx buffer waiting to be transmitted by the hardware.

Returns

The currently buffered number of bytes in our txBuff.

rxInUse

int

rxInUse

()

Description

Determines if the serial bus is currently in use by another fiber for reception.

Returns

The state of our mutex lock for reception.

Note

Only one fiber can call read at a time

txInUse

int

txInUse

()

Description

Determines if the serial bus is currently in use by another fiber for transmission.

Returns

The state of our mutex lock for transmition.

Note

Only one fiber can call send at a time

detach

void

detach

(

Serial::IrqType

interuptType)

Description

Detaches a previously configured interrupt

interruptType

one of Serial::RxIrq or Serial::TxIrq

Parameters

Serial::IrqType

interuptType

---