Hardware serial class. More...

#include <HardwareSerial.h>

Inheritance diagram for HardwareSerial:

Public Member Functions
	HardwareSerial (int uartPort)
	Create instance of a hardware serial port object. More...

void	setPort (int uartPort)

int	getPort ()

void	begin (uint32_t baud=9600)
	Initialise the serial port. More...

void	begin (uint32_t baud, SerialConfig config)
	Initialise and set its configuration. More...

void	begin (uint32_t baud, SerialConfig config, SerialMode mode)
	Initialise, set its configuration and mode. More...

void	begin (uint32_t baud, SerialConfig config, SerialMode mode, uint8_t txPin)

void	end ()
	De-inits the current UART if it is already used. More...

size_t	setRxBufferSize (size_t size)
	Sets receiving buffer size. More...

size_t	setTxBufferSize (size_t size)
	Sets transmit buffer size. More...

void	setTxWait (bool wait)
	Governs write behaviour when UART transmit buffers are full If false, writes will return short count; applications can use the txComplete callback to send more data. If true, writes will wait for more buffer space so that all requested data is written. More...

void	swap ()
	Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX. More...

void	swap (uint8_t tx_pin)
	Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX. More...

void	setTx (uint8_t tx_pin)
	Toggle between use of GPIO1 and GPIO2 as TX on UART 0. More...

void	pins (uint8_t tx, uint8_t rx)
	Sets the transmission and receiving PINS. More...

int	available () override
	Get quantity characters available from serial input. More...

int	read () override
	Read a character from serial port. More...

uint16_t	readMemoryBlock (char *buf, int max_len) override
	Read a block of characters from serial port. More...

bool	seek (int len) override
	Move read cursor. More...

bool	isFinished () override
	Check if all data has been read. More...

int	peek () override
	Read a character from serial port without removing from input buffer. More...

void	clear (SerialMode mode=SERIAL_FULL)
	Clear the serial port transmit/receive buffers. More...

void	flush () override
	Flush all pending data to the serial port. More...

size_t	write (const uint8_t *buffer, size_t size) override
	write multiple characters to serial port More...

void	systemDebugOutput (bool enabled)
	Configure serial port for system debug output and redirect output from debugf. More...

void	commandProcessing (bool reqEnable)
	Configure serial port for command processing. More...

bool	setCallback (StreamDataReceivedDelegate dataReceivedDelegate)
	Set handler for received data. More...

bool	onDataReceived (StreamDataReceivedDelegate dataReceivedDelegate)
	Set handler for received data. More...

bool	onTransmitComplete (TransmitCompleteDelegate transmitCompleteDelegate)
	Set handler for received data. More...

__forceinline void	setUartCallback (uart_callback_t callback, void *param=nullptr)
	Set callback ISR for received data. More...

bool	isTxEnabled ()
	Checks if the current UART can transmit(print) information. More...

bool	isRxEnabled ()
	Checks if the current UART can receive information. More...

uint32_t	baudRate ()
	Get the current baud rate. More...

uint32_t	setBaudRate (uint32_t baudrate)
	Attempt to set the requested baud rate. More...

	operator bool () const
	Operator that returns true if the uart structure is set. More...

int	indexOf (char c) override
	Returns the location of the searched character. More...

uart_t *	getUart ()
	Returns a pointer to the internal uart object. Use with care. More...

unsigned	getStatus ()
	Get status error flags and clear them. More...

size_t	write (uint8_t charToWrite) override
	Write a single character to the stream. More...

size_t	write (const char *str)
	Writes a c-string to output stream. More...

size_t	write (const char *buffer, size_t size)
	Writes characters from a buffer to output stream. More...

virtual StreamType	getStreamType () const
	Get the stream type. More...

virtual bool	isValid () const
	Determine if the stream object contains valid data. More...

int	length () SMING_DEPRECATED
	Return the total length of the stream. More...

virtual String	id () const
	Returns unique id of the resource. More...

virtual String	getName () const
	Returns name of the resource. More...

void	setTimeout (unsigned long timeout)

bool	find (char *target)

bool	find (char *target, size_t length)

bool	findUntil (char target, char terminator)

bool	findUntil (char target, size_t targetLen, char terminate, size_t termLen)

long	parseInt ()

float	parseFloat ()

size_t	readBytes (char *buffer, size_t length)

size_t	readBytesUntil (char terminator, char *buffer, size_t length)

String	readString ()

String	readStringUntil (char terminator)

int	getWriteError ()
	Gets last error. More...

void	clearWriteError ()
	Clears the last write error. More...

size_t	print (char)
	Prints a single character to output stream. More...

size_t	print (const char[])
	Prints a c-string to output stream. More...

size_t	print (unsigned long, int base=DEC)
	Prints a number to output stream. More...

size_t	print (long, int base=DEC)
	Prints a number to output stream. More...

size_t	print (unsigned int, int base=DEC)

size_t	print (unsigned char, int base=DEC)

size_t	print (int, int base=DEC)
	Prints a number to output stream. More...

size_t	print (double, int digits=2)
	Prints number to output stream. More...

size_t	print (const Printable &p)
	Prints a Printable object to output stream. More...

size_t	print (const String &s)
	Prints a String to output stream. More...

size_t	println (void)
	Prints a newline to output stream. More...

size_t	println (const char[])
	Prints a c-string to output stream, appending newline. More...

size_t	println (char)
	Prints a single character to output stream, appending newline. More...

size_t	println (unsigned char, int base=DEC)
	Prints a number to output stream, appending newline. More...

size_t	println (unsigned int, int base=DEC)

size_t	println (unsigned long, int base=DEC)

size_t	println (int, int base=DEC)
	Prints a number to output stream, appending newline. More...

size_t	println (long, int base=DEC)
	Prints a number to output stream, appending newline. More...

size_t	println (double, int digits=2)
	Prints a number to output stream, appending newline. More...

size_t	println (const Printable &p)
	Prints a Printable object to output stream, appending newline. More...

size_t	println (const String &s)
	Prints a String to output stream, appending newline. More...

size_t	printf (const char *fmt,...)
	Prints a formatted c-string to output stream. More...

Protected Member Functions
int	timedRead ()

int	timedPeek ()

int	peekNextDigit ()

long	parseInt (char skipChar)

float	parseFloat (char skipChar)

void	setWriteError (int err=1)

Protected Attributes
unsigned long	receiveTimeout = 1000

unsigned long	startMillis = 0

Detailed Description

Hardware serial class.

Constructor & Destructor Documentation

HardwareSerial::HardwareSerial ( int uartPort )

inline

Create instance of a hardware serial port object.

Parameters

uartPort UART number [0 | 1]

Note: A global instance of UART 0 is already defined as Serial

Member Function Documentation

int HardwareSerial::available ( )

inlineoverridevirtual

Get quantity characters available from serial input.

Return values

int	Quantity of characters in receive buffer

Reimplemented from IDataSourceStream.

uint32_t HardwareSerial::baudRate ( )

inline

Get the current baud rate.

Return values

uint32_t baud rate

void HardwareSerial::begin ( uint32_t baud = 9600 )

inline

Initialise the serial port.

Parameters

baud	BAUD rate of the serial port (Default: 9600)

void HardwareSerial::begin	(	uint32_t	baud,
		SerialConfig	config
	)

inline

Initialise and set its configuration.

Parameters

SerialConfig can be 5, 6, 7, 8 data bits, odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the desired mode, call Serial.begin(baudrate, SERIAL_8N1), Serial.begin(baudrate, SERIAL_6E2), etc.

void HardwareSerial::begin	(	uint32_t	baud,
		SerialConfig	config,
		SerialMode	mode
	)

inline

Initialise, set its configuration and mode.

Parameters

SerialConfig	can be 5, 6, 7, 8 data bits, odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the desired mode, call Serial.begin(baudrate, SERIAL_8N1), Serial.begin(baudrate, SERIAL_6E2), etc.
SerialMode	specifies if the UART supports receiving (RX), transmitting (TX) or both (FULL) operations

void HardwareSerial::clear ( SerialMode mode = SERIAL_FULL )

inline

Clear the serial port transmit/receive buffers.

Parameters

mode	Whether to flush TX, RX or both (the default)

Note: All un-read buffered data is removed and any error condition cleared

void Print::clearWriteError ( )

inlineinherited

Clears the last write error.

void HardwareSerial::commandProcessing ( bool reqEnable )

Configure serial port for command processing.

Parameters

reqEnable True to enable command processing

Note: Command processing provides a CLI to the system

See also: commandHandler

void HardwareSerial::end ( )

De-inits the current UART if it is already used.

void HardwareSerial::flush ( )

inlineoverridevirtual

Flush all pending data to the serial port.

Note: Not to be confused with uart_flush() which is different. See clear() method.

Reimplemented from IDataSourceStream.

virtual String IDataSourceStream::getName ( ) const

inlinevirtualinherited

Returns name of the resource.

Return values

String

Note: Commonly used to obtain name of file

Reimplemented in TemplateStream, FileStream, and GdbFileStream.

unsigned HardwareSerial::getStatus ( )

inline

Get status error flags and clear them.

Return values

unsigned Status flags, combination of SerialStatus bits

See also: SerialStatus

virtual StreamType IDataSourceStream::getStreamType ( ) const

inlinevirtualinherited

Get the stream type.

Return values

StreamType The stream type.

Reimplemented in FileStream, TemplateStream, StreamTransformer, rBootItemOutputStream, CircularBuffer, MemoryDataStream, LimitedMemoryStream, EndlessMemoryStream, UrlencodedOutputStream, FlashMemoryStream, JsonObjectStream, MultiStream, and ArduCAMStream.

uart_t* HardwareSerial::getUart ( )

inline

Returns a pointer to the internal uart object. Use with care.

Return values

pointer to uart_t

int Print::getWriteError ( )

inlineinherited

Gets last error.

Return values

int	Error number of last write error

virtual String IDataSourceStream::id ( ) const

inlinevirtualinherited

Returns unique id of the resource.

Return values

String the unique id of the stream.

Reimplemented in FileStream, GdbFileStream, and CircularBuffer.

int HardwareSerial::indexOf ( char c )

inlineoverridevirtual

Returns the location of the searched character.

Parameters

char	c - character to search for

Return values

int	-1 if not found 0 or positive number otherwise

Reimplemented from Stream.

bool HardwareSerial::isFinished ( )

inlineoverridevirtual

Check if all data has been read.

Return values

bool	True on success.

Implements IDataSourceStream.

bool HardwareSerial::isRxEnabled ( )

inline

Checks if the current UART can receive information.

Return values

bool	true if receiving is allowed

bool HardwareSerial::isTxEnabled ( )

inline

Checks if the current UART can transmit(print) information.

Return values

bool	true if transmitting is allowed

virtual bool IDataSourceStream::isValid ( ) const

inlinevirtualinherited

Determine if the stream object contains valid data.

Return values

bool	true if valid, false if invalid

Note: Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)

Reimplemented in FileStream, and GdbFileStream.

int IDataSourceStream::length ( )

inlineinherited

Return the total length of the stream.

Return values

int	-1 is returned when the size cannot be determined

Deprecated:: Use available() instead

bool HardwareSerial::onDataReceived ( StreamDataReceivedDelegate dataReceivedDelegate )

inline

Set handler for received data.

Parameters

dataReceivedDelegate Function to handle received data

Return values

bool	Returns true if the callback was set correctly

bool HardwareSerial::onTransmitComplete ( TransmitCompleteDelegate transmitCompleteDelegate )

inline

Set handler for received data.

Parameters

transmitCompleteDelegate Function to handle received data

Return values

bool	Returns true if the callback was set correctly

HardwareSerial::operator bool ( ) const

inline

Operator that returns true if the uart structure is set.

int HardwareSerial::peek ( )

inlineoverridevirtual

Read a character from serial port without removing from input buffer.

Return values

int	Character read from serial port or -1 if buffer empty

Note: The character remains in serial port input buffer

Reimplemented from IDataSourceStream.

void HardwareSerial::pins	(	uint8_t	tx,
		uint8_t	rx
	)

inline

Sets the transmission and receiving PINS.

Parameters

uint8_t	tx Transmission pin number
uint8_t	rx Receiving pin number

Note: UART 0 possible options are (1, 3), (2, 3) or (15, 13); UART 1 allows only TX on 2 if UART 0 is not (2, 3)

size_t Print::print ( char )

inherited

Prints a single character to output stream.

Return values

size_t Quantity of characters written to stream

size_t Print::print ( const char [] )

inherited

Prints a c-string to output stream.

Parameters

char[] c-string to print

Return values

size_t	Quantity of characters written to output stream
size_t	Quantity of characters written to stream

size_t Print::print	(	unsigned	char,
		int	base = `DEC`
	)

inherited

Prints a number to output stream.

Parameters

unsigned long	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

Parameters

unsigned int	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

Parameters

unsigned char	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

size_t Print::print	(	long	,
		int	base = `DEC`
	)

inherited

Prints a number to output stream.

Parameters

long	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

size_t Print::print	(	int	,
		int	base = `DEC`
	)

inherited

Prints a number to output stream.

Parameters

int	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

size_t Print::print	(	double	,
		int	digits = `2`
	)

inherited

Prints number to output stream.

Prints a number to output stream.

Parameters

double	Number to print
int	Decimal places to show

Return values

size_t Quantity of characters written to output stream

Parameters

double	Number to print
digits	The decimal places to print (Default: 2, e.g. 21.35)

Return values

size_t Quantity of characters written to stream

size_t Print::print ( const Printable & p )

inherited

Prints a Printable object to output stream.

Parameters

p	Object to print

Return values

size_t Quantity of characters written to stream

size_t Print::print ( const String & s )

inherited

Prints a String to output stream.

Parameters

s	String to print

Return values

size_t Quantity of characters written to stream

size_t Print::printf	(	const char *	fmt,
			...
	)

inherited

Prints a formatted c-string to output stream.

Parameters

fmt	Pointer to formated c-string to print
...	Parameters for placeholders within formated string

Return values

size_t Quantity of characters written to stream

Note: Use standard printf placeholders, e.g. d for integer, s for c-string, etc.

size_t Print::println ( void )

inherited

Prints a newline to output stream.

Parameters

Prints newline to output stream

Return values

size_t	Quantity of characters written to output stream
size_t	Quantity of characters written to stream

size_t Print::println ( const char [] )

inherited

Prints a c-string to output stream, appending newline.

Parameters

char[] c-string to print

Return values

size_t Quantity of characters written to stream

size_t Print::println ( char )

inherited

Prints a single character to output stream, appending newline.

Parameters

char	Character to print

Return values

size_t Quantity of characters written to stream

size_t Print::println	(	unsigned	long,
		int	base = `DEC`
	)

inherited

Prints a number to output stream, appending newline.

Parameters

unsigned char	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

Parameters

unsigned int	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

Parameters

unsigned long	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

size_t Print::println	(	int	,
		int	base = `DEC`
	)

inherited

Prints a number to output stream, appending newline.

Parameters

int	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

size_t Print::println	(	long	,
		int	base = `DEC`
	)

inherited

Prints a number to output stream, appending newline.

Parameters

long	Number to print
base	The base for output (Default: Decimal (base 10))

Return values

size_t Quantity of characters written to stream

size_t Print::println	(	double	,
		int	digits = `2`
	)

inherited

Prints a number to output stream, appending newline.

Parameters

double	Number to print
digits	The decimal places to print (Default: 2, e.g. 21.35)

Return values

size_t Quantity of characters written to stream

size_t Print::println ( const Printable & p )

inherited

Prints a Printable object to output stream, appending newline.

Parameters

p	Object to print

Return values

size_t Quantity of characters written to stream

size_t Print::println ( const String & s )

inherited

Prints a String to output stream, appending newline.

Parameters

s	String to print

Return values

size_t Quantity of characters written to stream

int HardwareSerial::read ( )

inlineoverridevirtual

Read a character from serial port.

Return values

int	Character read from serial port or -1 if buffer empty

Note: The character is removed from the serial port input buffer

Reimplemented from IDataSourceStream.

uint16_t HardwareSerial::readMemoryBlock	(	char *	buf,
		int	max_len
	)

inlineoverridevirtual

Read a block of characters from serial port.

Parameters

buf	Pointer to buffer to hold received data
max_len	Maximum quantity of characters to read

Return values

size_t Quantity of characters read

Note: Although this shares the same name as the method in IDataSourceStream, behaviour is different because in effect the 'seek' position is changed by this call.

Implements IDataSourceStream.

bool HardwareSerial::seek ( int len )

inlineoverridevirtual

Move read cursor.

Parameters

len	Relative cursor adjustment

Return values

bool	True on success.

Implements IDataSourceStream.

uint32_t HardwareSerial::setBaudRate ( uint32_t baudrate )

inline

Attempt to set the requested baud rate.

Return values

uint32_t the actual baud rate in force

Note: Return value may differ from requested baud rate due to clock division errors

bool HardwareSerial::setCallback ( StreamDataReceivedDelegate dataReceivedDelegate )

inline

Set handler for received data.

Parameters

dataReceivedDelegate Function to handle received data

Return values

bool	Returns true if the callback was set correctly

size_t HardwareSerial::setRxBufferSize ( size_t size )

Sets receiving buffer size.

Parameters

size_t requested size

Return values

size_t actual size

void HardwareSerial::setTx ( uint8_t tx_pin )

inline

Toggle between use of GPIO1 and GPIO2 as TX on UART 0.

Note: : UART 1 can't be used if GPIO2 is used with UART 0!; : If UART1 is not used and UART0 is not swapped - TX for UART0 can be mapped to GPIO2 by calling .setTx(2) after .begin or directly with .begin(baud, config, mode, 2).

size_t HardwareSerial::setTxBufferSize ( size_t size )

Sets transmit buffer size.

Parameters

size_t requested size

Return values

size_t actual size

void HardwareSerial::setTxWait ( bool wait )

inline

Governs write behaviour when UART transmit buffers are full If false, writes will return short count; applications can use the txComplete callback to send more data. If true, writes will wait for more buffer space so that all requested data is written.

__forceinline void HardwareSerial::setUartCallback	(	uart_callback_t	callback,
		void *	param = `nullptr`
	)

inline

Set callback ISR for received data.

Parameters

reqCallback Function to handle received data

Note: callback is invoked directly from serial ISR and bypasses any registered delgates

void HardwareSerial::swap ( )

inline

Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX.

Note: UART0 uses pins GPIO1 (TX) and GPIO3 (RX). It may be swapped to GPIO15 (TX) and GPIO13 (RX) by calling .swap() after .begin. C; Calling swap again maps UART0 back to GPIO1 and GPIO3.

void HardwareSerial::swap ( uint8_t tx_pin )

inline

Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX.

Parameters

uint8_t Pin number.

void HardwareSerial::systemDebugOutput ( bool enabled )

Configure serial port for system debug output and redirect output from debugf.

Parameters

enabled True to enable this port for system debug output

Note: If enabled, port will issue system debug messages

size_t ReadWriteStream::write ( uint8_t charToWrite )

inlineoverridevirtualinherited

Write a single character to the stream.

Parameters

charToWrite

Return values

size_t Number of chars written (1 on success, 0 on failure)

Reimplemented from IDataSourceStream.

size_t Print::write ( const char * str )

inlineinherited

Writes a c-string to output stream.

Parameters

str	Pointer to c-string

Return values

size_t Quantity of characters written to stream

size_t Print::write	(	const char *	buffer,
		size_t	size
	)

inlineinherited

Writes characters from a buffer to output stream.

Parameters

buffer	Pointer to character buffer
size	Quantity of characters to write

Return values

size_t Quantity of characters written to stream

size_t HardwareSerial::write	(	const uint8_t *	buffer,
		size_t	size
	)

inlineoverridevirtual

write multiple characters to serial port

Parameters

buffer	data to write
size	number of characters to write

Return values

size_t Quantity of characters written, may be less than size

Implements ReadWriteStream.

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation