Class definition for MicroBitSerial. More...

#include <MicroBitSerial.h>

Public Member Functions
	MicroBitSerial (PinName tx, PinName rx, uint8_t rxBufferSize=MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE, uint8_t txBufferSize=MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE)
	Constructor.
int	sendChar (char c, MicroBitSerialMode mode=MICROBIT_DEFAULT_SERIAL_MODE)
	Sends a single character over the serial line.
int	send (ManagedString s, MicroBitSerialMode mode=MICROBIT_DEFAULT_SERIAL_MODE)
	Sends a ManagedString over the serial line.
int	send (uint8_t *buffer, int bufferLen, MicroBitSerialMode mode=MICROBIT_DEFAULT_SERIAL_MODE)
	Sends a buffer of known length over the serial line.
int	read (MicroBitSerialMode mode=MICROBIT_DEFAULT_SERIAL_MODE)
	Reads a single character from the rxBuff.
ManagedString	read (int size, MicroBitSerialMode mode=MICROBIT_DEFAULT_SERIAL_MODE)
	Reads multiple characters from the rxBuff and returns them as a ManagedString.
int	read (uint8_t *buffer, int bufferLen, MicroBitSerialMode mode=MICROBIT_DEFAULT_SERIAL_MODE)
	Reads multiple characters from the rxBuff and fills a user buffer.
ManagedString	readUntil (ManagedString delimeters, MicroBitSerialMode mode=MICROBIT_DEFAULT_SERIAL_MODE)
	Reads until one of the delimeters matches a character in the rxBuff.
void	baud (int baudrate)
	A wrapper around the inherited method "baud" so we can trap the baud rate as it changes and restore it if redirect() is called.
int	redirect (PinName tx, PinName rx)
	A way of dynamically configuring the serial instance to use pins other than USBTX and USBRX.
int	eventAfter (int len, MicroBitSerialMode mode=ASYNC)
	Configures an event to be fired after "len" characters.
int	eventOn (ManagedString delimeters, MicroBitSerialMode mode=ASYNC)
	Configures an event to be fired on a match with one of the delimeters.
int	isReadable ()
	Determines whether there is any data waiting in our Rx buffer.
int	isWriteable ()
	Determines if we have space in our txBuff.
int	setRxBufferSize (uint8_t size)
	Reconfigures the size of our rxBuff.
int	setTxBufferSize (uint8_t size)
	Reconfigures the size of our txBuff.
int	getRxBufferSize ()
	The size of our rx buffer in bytes.
int	getTxBufferSize ()
	The size of our tx buffer in bytes.
int	clearRxBuffer ()
	Sets the tail to match the head of our circular buffer for reception, effectively clearing the reception buffer.
int	clearTxBuffer ()
	Sets the tail to match the head of our circular buffer for transmission, effectively clearing the transmission buffer.
int	rxBufferedSize ()
	The number of bytes currently stored in our rx buffer waiting to be digested, by the user.
int	txBufferedSize ()
	The number of bytes currently stored in our tx buffer waiting to be transmitted by the hardware.
int	rxInUse ()
	Determines if the serial bus is currently in use by another fiber for reception.
int	txInUse ()
	Determines if the serial bus is currently in use by another fiber for transmission.
void	detach (Serial::IrqType interuptType)
	Detaches a previously configured interrupt.

Detailed Description

Class definition for MicroBitSerial.

Represents an instance of RawSerial which accepts micro:bit specific data types.

Definition at line 57 of file MicroBitSerial.h.

Constructor & Destructor Documentation

MicroBitSerial	(	PinName	tx,
		PinName	rx,
		uint8_t	rxBufferSize = `MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE`,
		uint8_t	txBufferSize = `MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE`
	)

Constructor.

Create an instance of MicroBitSerial

Parameters:

tx	the Pin to be used for transmission
rx	the Pin to be used for receiving data
rxBufferSize	the size of the buffer to be used for receiving bytes
txBufferSize	the size of the buffer to be used for transmitting bytes

 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

Buffers aren't allocated until the first send or receive respectively.

Definition at line 58 of file MicroBitSerial.cpp.

Member Function Documentation

void baud ( int baudrate )

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:

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.

Definition at line 811 of file MicroBitSerial.cpp.

int clearRxBuffer ( )

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.

Definition at line 1031 of file MicroBitSerial.cpp.

int clearTxBuffer ( )

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.

Definition at line 1052 of file MicroBitSerial.cpp.

void detach ( Serial::IrqType interruptType )

Detaches a previously configured interrupt.

Parameters:

interruptType one of Serial::RxIrq or Serial::TxIrq

Definition at line 1123 of file MicroBitSerial.cpp.

int eventAfter	(	int	len,
		MicroBitSerialMode	mode = `ASYNC`
	)

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:

len	the number of characters to wait before triggering the event.
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.

Definition at line 877 of file MicroBitSerial.cpp.

int eventOn	(	ManagedString	delimeters,
		MicroBitSerialMode	mode = `ASYNC`
	)

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:

delimeters	the characters to match received characters against e.g. ManagedString("\n")
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.

Definition at line 913 of file MicroBitSerial.cpp.

int getRxBufferSize ( )

The size of our rx buffer in bytes.

Returns:: the current size of rxBuff in bytes

Definition at line 1009 of file MicroBitSerial.cpp.

int getTxBufferSize ( )

The size of our tx buffer in bytes.

Returns:: the current size of txBuff in bytes

Definition at line 1019 of file MicroBitSerial.cpp.

int isReadable ( )

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

Definition at line 936 of file MicroBitSerial.cpp.

int isWriteable ( )

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

Definition at line 949 of file MicroBitSerial.cpp.

ManagedString read	(	int	size,
		MicroBitSerialMode	mode = `MICROBIT_DEFAULT_SERIAL_MODE`
	)

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

Parameters:

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.

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

Definition at line 585 of file MicroBitSerial.cpp.

int read ( MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE )

Reads a single character from the rxBuff.

Parameters:

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.

Definition at line 538 of file MicroBitSerial.cpp.

int read	(	uint8_t *	buffer,
		int	bufferLen,
		MicroBitSerialMode	mode = `MICROBIT_DEFAULT_SERIAL_MODE`
	)

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

Parameters:

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.

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

Definition at line 626 of file MicroBitSerial.cpp.

ManagedString readUntil	(	ManagedString	delimeters,
		MicroBitSerialMode	mode = `MICROBIT_DEFAULT_SERIAL_MODE`
	)

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

Parameters:

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.

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.

Definition at line 711 of file MicroBitSerial.cpp.

int redirect	(	PinName	tx,
		PinName	rx
	)

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

Parameters:

tx	the new transmission pin.
rx	the new reception pin.

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

Definition at line 830 of file MicroBitSerial.cpp.

int rxBufferedSize ( )

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.

Definition at line 1072 of file MicroBitSerial.cpp.

int rxInUse ( )

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

Definition at line 1101 of file MicroBitSerial.cpp.

int send	(	uint8_t *	buffer,
		int	bufferLen,
		MicroBitSerialMode	mode = `MICROBIT_DEFAULT_SERIAL_MODE`
	)

Sends a buffer of known length over the serial line.

Parameters:

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.

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.

Definition at line 479 of file MicroBitSerial.cpp.

int send	(	ManagedString	s,
		MicroBitSerialMode	mode = `MICROBIT_DEFAULT_SERIAL_MODE`
	)

Sends a ManagedString over the serial line.

Parameters:

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.

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.

Definition at line 448 of file MicroBitSerial.cpp.

int sendChar	(	char	c,
		MicroBitSerialMode	mode = `MICROBIT_DEFAULT_SERIAL_MODE`
	)

Sends a single character over the serial line.

Parameters:

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.

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

Definition at line 397 of file MicroBitSerial.cpp.

int setRxBufferSize ( uint8_t size )

Reconfigures the size of our rxBuff.

Parameters:

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.

Definition at line 962 of file MicroBitSerial.cpp.

int setTxBufferSize ( uint8_t size )

Reconfigures the size of our txBuff.

Parameters:

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.

Definition at line 987 of file MicroBitSerial.cpp.

int txBufferedSize ( )

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.

Definition at line 1086 of file MicroBitSerial.cpp.

int txInUse ( )

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

Definition at line 1113 of file MicroBitSerial.cpp.

Type:	Library
Created:	07 Apr 2016
Imports:	461
Forks:	13
Commits:	74
Dependents:	5
Dependencies:	3
Followers:	54

MicroBitSerial Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

MicroBitSerial Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning