Hardware serial class. More...

#include <HardwareSerial.h>

Inheritance diagram for HardwareSerial:

Collaboration diagram for HardwareSerial:

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

void	setPort (int uartPort)

int	getPort ()

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

bool	begin (uint32_t baud, SerialFormat format)
	Initialise and set its configuration. More...

bool	begin (uint32_t baud, SerialFormat format, SerialMode mode)
	Initialise, set its configuration and mode. More...

bool	begin (uint32_t baud, SerialFormat format, SerialMode mode, uint8_t txPin, uint8_t rxPin=SERIAL_PIN_DEFAULT)
	Initialise, set its configuration and mode. More...

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. 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	onDataReceived (StreamDataReceivedDelegate dataReceivedDelegate)
	Set handler for received data. More...

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

void	setUartCallback (smg_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...

smg_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...

Public Member Functions inherited from ReadWriteStream
size_t	write (uint8_t charToWrite) override
	From Stream class: We don't write using this stream. More...

virtual size_t	copyFrom (IDataSourceStream *source, size_t size=SIZE_MAX)
	Copy data from a source stream. More...

virtual size_t	write (uint8_t c)=0
	Writes a single character to output stream. More...

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

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

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

Public Member Functions inherited from IDataSourceStream
virtual StreamType	getStreamType () const
	Get the stream type. More...

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

size_t	readBytes (char *buffer, size_t length) override
	Read chars from stream into buffer. More...

virtual int	seekFrom (int offset, SeekOrigin origin)
	Change position in stream. More...

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

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

virtual MimeType	getMimeType () const
	Get MIME type for stream content. More...

String	readString (size_t maxLen) override
	Overrides Stream method for more efficient reading. More...

virtual bool	moveString (String &s)
	Memory-based streams may be able to move content into a String. More...

virtual size_t	readBytes (char *buffer, size_t length)
	Read chars from stream into buffer. More...

size_t	readBytes (uint8_t *buffer, size_t length)

Public Member Functions inherited from Stream
	Stream ()

void	setTimeout (unsigned long timeout)
	Set maximum milliseconds to wait for stream data, default is 1 second. More...

bool	find (const char *target)
	Read data from the stream until the target string is found. More...

bool	find (const char *target, size_t length)
	Read data from the stream until the target string of given length is found. More...

bool	findUntil (const char target, const char terminator)
	As `find()` but search ends if the terminator string is found. More...

bool	findUntil (const char target, size_t targetLen, const char terminate, size_t termLen)
	As `findUntil(const char, const char)` but search ends if the terminate string is found. More...

long	parseInt ()
	Returns the first valid (long) integer value from the current position. More...

float	parseFloat ()
	float version of parseInt More...

size_t	readBytes (uint8_t *buffer, size_t length)

size_t	readBytesUntil (char terminator, char *buffer, size_t length)
	As `readBytes()` with terminator character. More...

String	readStringUntil (char terminator)

Public Member Functions inherited from Print
virtual	~Print ()

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

void	clearWriteError ()
	Clears the last write error. 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...

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

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

size_t	print (double num, int digits=2)
	Print a floating-point number to output stream. More...

template<typename T >
std::enable_if< has_printTo< T >::value, size_t >::type	print (const T &obj)
	Prints a Printable object to output stream. More...

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

template<typename E >
std::enable_if< std::is_enum< E >::value &&!std::is_convertible< E, int >::value, size_t >::type	print (E value)
	enums can be printed as strings provided they have a `toString(E)` implementation. More...

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

template<typename... Args>
size_t	println (const Args &... args)
	Print value plus newline to output stream. More...

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

size_t	print (unsigned long num, uint8_t base=DEC)

template<typename... Args>
size_t	print (unsigned long num, Args... args)

template<typename... Args>
size_t	print (const unsigned long long &num, Args... args)

size_t	print (long num, uint8_t base=DEC)

template<typename... Args>
size_t	print (long num, Args... args)

template<typename... Args>
size_t	print (const long long &num, Args... args)

template<typename... Args>
size_t	print (unsigned int num, Args... args)

template<typename... Args>
size_t	print (unsigned char num, Args... args)

template<typename... Args>
size_t	print (int num, Args... args)

Additional Inherited Members
Protected Member Functions inherited from Stream
int	timedRead ()

int	timedPeek ()

int	peekNextDigit ()
	returns the next numeric digit in the stream or -1 if timeout More...

long	parseInt (char skipChar)
	Like regular `parseInt()` but the given skipChar is ignored. More...

float	parseFloat (char skipChar)
	Like `parseInt(skipChar)` for float. More...

Protected Member Functions inherited from Print
void	setWriteError (int err=1)

Protected Attributes inherited from Stream
uint16_t	receiveTimeout = 1000
	number of milliseconds to wait for the next char before aborting timed read More...

Detailed Description

Hardware serial class.

Constructor & Destructor Documentation

◆ HardwareSerial()

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

◆ available()

int HardwareSerial::available ( )

inlineoverridevirtual

Get quantity characters available from serial input.

Return values

int	Quantity of characters in receive buffer

Reimplemented from IDataSourceStream.

◆ baudRate()

uint32_t HardwareSerial::baudRate ( )

inline

Get the current baud rate.

Return values

uint32_t baud rate

◆ begin() [1/4]

bool HardwareSerial::begin	(	uint32_t	baud,
		SerialFormat	format
	)

inline

Initialise and set its configuration.

Parameters

baud	Baud rate to use
format	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.

Return values

bool	true on success

◆ begin() [2/4]

bool HardwareSerial::begin	(	uint32_t	baud,
		SerialFormat	format,
		SerialMode	mode
	)

inline

Initialise, set its configuration and mode.

Parameters

baud	Baud rate to use
format	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.
mode	specifies if the UART supports receiving (RX), transmitting (TX) or both (FULL) operations

Return values

bool	true on success

◆ begin() [3/4]

bool HardwareSerial::begin	(	uint32_t	baud,
		SerialFormat	format,
		SerialMode	mode,
		uint8_t	txPin,
		uint8_t	rxPin = `SERIAL_PIN_DEFAULT`
	)

Initialise, set its configuration and mode.

Parameters

baud	Baud rate to use
format
mode
txPin	Can specify alternate pin for TX
rxPin

Return values

bool	true on success

◆ begin() [4/4]

bool HardwareSerial::begin ( uint32_t baud = 9600 )

inline

Initialise the serial port.

Parameters

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

Return values

bool	true on success

◆ clear()

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

◆ commandProcessing()

void HardwareSerial::commandProcessing ( bool reqEnable )

inline

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

Deprecated:: include <Services/CommandProcessing/Utils.h> and use CommandProcessing::enable(Handler, Serial) instead.

◆ end()

void HardwareSerial::end ( )

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

◆ flush()

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.

◆ getPort()

int HardwareSerial::getPort ( )

inline

◆ getStatus()

unsigned HardwareSerial::getStatus ( )

Get status error flags and clear them.

Return values

unsigned Status flags, combination of SerialStatus bits

See also: SerialStatus

◆ getUart()

smg_uart_t* HardwareSerial::getUart ( )

inline

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

Return values

pointer to uart_t

◆ indexOf()

int HardwareSerial::indexOf ( char c )

inlineoverridevirtual

Returns the location of the searched character.

Parameters

c	- character to search for

Return values

int	-1 if not found 0 or positive number otherwise

Reimplemented from Stream.

◆ isFinished()

bool HardwareSerial::isFinished ( )

inlineoverridevirtual

Check if all data has been read.

Return values

bool	True on success.

Implements IDataSourceStream.

◆ isRxEnabled()

bool HardwareSerial::isRxEnabled ( )

inline

Checks if the current UART can receive information.

Return values

bool	true if receiving is allowed

◆ isTxEnabled()

bool HardwareSerial::isTxEnabled ( )

inline

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

Return values

bool	true if transmitting is allowed

◆ onDataReceived()

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

◆ onTransmitComplete()

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

◆ operator bool()

HardwareSerial::operator bool ( ) const

inline

Operator that returns true if the uart structure is set.

◆ peek()

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.

◆ pins()

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

inline

Sets the transmission and receiving PINS.

Parameters

tx	Transmission pin number
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)

◆ read()

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.

◆ readMemoryBlock()

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

uint16_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.

◆ seek()

bool HardwareSerial::seek ( int len )

inlineoverridevirtual

Move read cursor.

Parameters

len	Relative cursor adjustment

Return values

bool	True on success.

Reimplemented from IDataSourceStream.

◆ setBaudRate()

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

◆ setPort()

void HardwareSerial::setPort ( int uartPort )

inline

◆ setRxBufferSize()

size_t HardwareSerial::setRxBufferSize ( size_t size )

Sets receiving buffer size.

Parameters

size	requested size

Return values

size_t actual size

◆ setTx()

void HardwareSerial::setTx ( uint8_t tx_pin )

inline

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

Parameters

tx_pin

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

◆ setTxBufferSize()

size_t HardwareSerial::setTxBufferSize ( size_t size )

Sets transmit buffer size.

Parameters

size	requested size

Return values

size_t actual size

◆ setTxWait()

void HardwareSerial::setTxWait ( bool wait )

inline

Governs write behaviour when UART transmit buffers are full.

Parameters

wait	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

◆ setUartCallback()

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

inline

Set callback ISR for received data.

Parameters

callback	Function to handle received data
param	Set as return value for `uart_get_callback_param()`

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

◆ swap() [1/2]

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.

◆ swap() [2/2]

void HardwareSerial::swap ( uint8_t tx_pin )

inline

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

Parameters

tx_pin Pin number.

◆ systemDebugOutput()

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

◆ write()

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.

The documentation for this class was generated from the following file:

HardwareSerial.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ HardwareSerial()

Member Function Documentation

◆ available()

◆ baudRate()

◆ begin() [1/4]

◆ begin() [2/4]

◆ begin() [3/4]

◆ begin() [4/4]

◆ clear()

◆ commandProcessing()

◆ end()

◆ flush()

◆ getPort()

◆ getStatus()

◆ getUart()

◆ indexOf()

◆ isFinished()

◆ isRxEnabled()

◆ isTxEnabled()

◆ onDataReceived()

◆ onTransmitComplete()

◆ operator bool()

◆ peek()

◆ pins()

◆ read()

◆ readMemoryBlock()

◆ seek()

◆ setBaudRate()

◆ setPort()

◆ setRxBufferSize()

◆ setTx()

◆ setTxBufferSize()

◆ setTxWait()

◆ setUartCallback()

◆ swap() [1/2]

◆ swap() [2/2]

◆ systemDebugOutput()

◆ write()