Lancaster University / microbit-dal

mbed.org local branch of microbit-dal. The real version lives in git at https://github.com/lancaster-university/microbit-dal

Dependencies:   BLE_API nRF51822 mbed-dev-bin

Dependents:   microbit Microbit IoTChallenge1 microbit ... more

Embed: (wiki syntax)

« Back to documentation index

MicroBitUARTService Class Reference
Public Member Functions

MicroBitUARTService Class Reference

Class definition for the custom MicroBit UART Service. More...

#include <MicroBitUARTService.h>

Public Member Functions

 MicroBitUARTService (BLEDevice &_ble, uint8_t rxBufferSize=MICROBIT_UART_S_DEFAULT_BUF_SIZE, uint8_t txBufferSize=MICROBIT_UART_S_DEFAULT_BUF_SIZE)
 Constructor for the UARTService.
int getc (MicroBitSerialMode mode=SYNC_SLEEP)
 Retreives a single character from our RxBuffer.
int putc (char c, MicroBitSerialMode mode=SYNC_SLEEP)
 Places a single character into our transmission buffer,.
int send (const uint8_t *buf, int length, MicroBitSerialMode mode=SYNC_SLEEP)
 Copies characters into the buffer used for Transmitting to the central device.
int send (ManagedString s, MicroBitSerialMode mode=SYNC_SLEEP)
 Copies characters into the buffer used for Transmitting to the central device.
int read (uint8_t *buf, int len, MicroBitSerialMode mode=SYNC_SLEEP)
 Reads a number of characters from the rxBuffer and fills user given buffer.
ManagedString read (int len, MicroBitSerialMode mode=SYNC_SLEEP)
 Reads a number of characters from the rxBuffer and returns them as a ManagedString.
ManagedString readUntil (ManagedString delimeters, MicroBitSerialMode mode=SYNC_SLEEP)
 Reads characters until a character matches one of the given delimeters.
int eventOn (ManagedString delimeters, MicroBitSerialMode mode=ASYNC)
 Configures an event to be fired on a match with one of the delimeters.
int eventAfter (int len, MicroBitSerialMode mode=ASYNC)
 Configures an event to be fired after "len" characters.
int isReadable ()
 Determines if we have space in our rxBuff.
int rxBufferedSize ()
int txBufferedSize ()

Detailed Description

Class definition for the custom MicroBit UART Service.

Provides a BLE service that acts as a UART port, enabling the reception and transmission of an arbitrary number of bytes.

Definition at line 46 of file MicroBitUARTService.h.

Constructor & Destructor Documentation

MicroBitUARTService ( BLEDevice &  _ble,
uint8_t  rxBufferSize = MICROBIT_UART_S_DEFAULT_BUF_SIZE,
uint8_t  txBufferSize = MICROBIT_UART_S_DEFAULT_BUF_SIZE 
)

Constructor for the UARTService.

Parameters:
_blean instance of BLEDevice
rxBufferSizethe size of the rxBuffer
txBufferSizethe size of the txBuffer
Note:
The default size is MICROBIT_UART_S_DEFAULT_BUF_SIZE (20 bytes).
Parameters:
_blean instance of BLEDevice
rxBufferSizethe size of the rxBuffer
txBufferSizethe size of the txBuffer
Note:
defaults to 20

Definition at line 65 of file MicroBitUARTService.cpp.

Member Function Documentation

int eventAfter ( int  len,
MicroBitSerialMode  mode = ASYNC 
)

Configures an event to be fired after "len" characters.

Parameters:
lenthe number of characters to wait before triggering the event
modethe 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 534 of file MicroBitUARTService.cpp.

int eventOn ( ManagedString  delimeters,
MicroBitSerialMode  mode = ASYNC 
)

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

Parameters:
delimetersthe characters to match received characters against e.g. ManagedString("\r\n")
modethe 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 503 of file MicroBitUARTService.cpp.

int getc ( MicroBitSerialMode  mode = SYNC_SLEEP )

Retreives a single character from our RxBuffer.

Parameters:
modethe selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode gives a different behaviour:

ASYNC - Will attempt to read a single character, 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, a character or MICROBIT_NO_DATA

Definition at line 181 of file MicroBitUARTService.cpp.

int isReadable (  )

Determines if we have space in our rxBuff.

Returns:
1 if we have space, 0 if we do not.
1 if we have space, 0 if we do not.
Note:
the reason we do not wrap the super's readable() method is so that we don't interfere with communities that use manual calls to uBit.serial.readable()

Definition at line 557 of file MicroBitUARTService.cpp.

int putc ( char  c,
MicroBitSerialMode  mode = SYNC_SLEEP 
)

Places a single character into our transmission buffer,.

places a single character into our transmission buffer,

Parameters:
cthe character to transmit
modethe selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode gives a different behaviour:

ASYNC - Will copy as many characters as it can into the buffer for transmission, and return control to the user.

SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER

SYNC_SLEEP - Will perform a cooperative blocking wait until all given characters have been received by the connected device.

Returns:
the number of characters written, or MICROBIT_NOT_SUPPORTED if there is no connected device, or the connected device has not enabled indications.

Definition at line 225 of file MicroBitUARTService.cpp.

int read ( uint8_t *  buf,
int  len,
MicroBitSerialMode  mode = SYNC_SLEEP 
)

Reads a number of characters from the rxBuffer and fills user given buffer.

Parameters:
bufa pointer to a buffer of len bytes.
lenthe size of the user allocated buffer
modethe selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode gives a different behaviour:

ASYNC - Will attempt to read all available characters, and return immediately until the buffer limit is reached

SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER

SYNC_SLEEP - Will first of all determine whether the given number of characters are available in our buffer, if not, it will set an event and sleep until the number of characters are avaialable.

Returns:
the number of characters digested

Definition at line 348 of file MicroBitUARTService.cpp.

ManagedString read ( int  len,
MicroBitSerialMode  mode = SYNC_SLEEP 
)

Reads a number of characters from the rxBuffer and returns them as a ManagedString.

Parameters:
lenthe number of characters to read.
modethe selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode gives a different behaviour:

ASYNC - Will attempt to read all available characters, and return immediately until the buffer limit is reached

SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER

SYNC_SLEEP - Will first of all determine whether the given number of characters are available in our buffer, if not, it will set an event and sleep until the number of characters are avaialable.

Returns:
an empty ManagedString on error, or a ManagedString containing characters

Definition at line 399 of file MicroBitUARTService.cpp.

ManagedString readUntil ( ManagedString  delimeters,
MicroBitSerialMode  mode = SYNC_SLEEP 
)

Reads characters until a character matches one of the given delimeters.

Parameters:
delimetersthe number of characters to match against
modethe selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode gives a different behaviour:

ASYNC - Will attempt read the immediate buffer, and look for a match. If there isn't, an empty ManagedString will be returned.

SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER

SYNC_SLEEP - Will first of all consider the characters in the immediate buffer, if a match is not found, it will block on an event, fired when a character is matched.

Returns:
an empty ManagedString on error, or a ManagedString containing characters

Definition at line 431 of file MicroBitUARTService.cpp.

int rxBufferedSize (  )
Returns:
The currently buffered number of bytes in our rxBuff.

Definition at line 565 of file MicroBitUARTService.cpp.

int send ( ManagedString  s,
MicroBitSerialMode  mode = SYNC_SLEEP 
)

Copies characters into the buffer used for Transmitting to the central device.

Parameters:
sthe string to transmit
modethe selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode gives a different behaviour:

ASYNC - Will copy as many characters as it can into the buffer for transmission, and return control to the user.

SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER

SYNC_SLEEP - Will perform a cooperative blocking wait until all given characters have been received by the connected device.

Returns:
the number of characters written, or MICROBIT_NOT_SUPPORTED if there is no connected device, or the connected device has not enabled indications.

Definition at line 324 of file MicroBitUARTService.cpp.

int send ( const uint8_t *  buf,
int  length,
MicroBitSerialMode  mode = SYNC_SLEEP 
)

Copies characters into the buffer used for Transmitting to the central device.

Parameters:
bufa buffer containing length number of bytes.
lengththe size of the buffer.
modethe selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode gives a different behaviour:

ASYNC - Will copy as many characters as it can into the buffer for transmission, and return control to the user.

SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER

SYNC_SLEEP - Will perform a cooperative blocking wait until all given characters have been received by the connected device.

Returns:
the number of characters written, or MICROBIT_NOT_SUPPORTED if there is no connected device, or the connected device has not enabled indications.

Definition at line 250 of file MicroBitUARTService.cpp.

int txBufferedSize (  )
Returns:
The currently buffered number of bytes in our txBuff.

Definition at line 576 of file MicroBitUARTService.cpp.

Generated on Tue Jul 12 2022 15:22:57 by  doxygen 1.7.2