Provides a high-end interface to serial communications using USART3. More...

#include <USART3.h>

Inheritance diagram for Serial3:

Collaboration diagram for Serial3:

Public Types
enum	IntegerOutputBase { kBin = 2, kOct = 8, kDec = 10, kHex = 16 }
	An enumeration that defines the number that will be used as the base for representing integer quantities as a string of characters. More...

Public Member Functions
void	start (unsigned long baudRate, UsartSerialConfiguration config=kSerial_8N1)
	Configure the hardware for two-way serial communications, including turning on associated interrupts. You must call this function before reading from or writing to Serial3 on USART3. More...

void	stop ()
	Stops buffered serial communications using Serial3 on USART3 by deconfiguring the hardware and turning off interrupts. More...

virtual size_t	write (char c)
	Write a single character to the output stream. This implements the pure virtual function Writer::write( char c ). More...

virtual size_t	write (const char *str)
	Write a null-terminated string to the output stream. This implements the pure virtual function Writer::write( char* str ). More...

virtual size_t	write (const char *buffer, size_t size)
	Write a given number of characters from a buffer to the output stream. This implements the pure virtual function Writer::write( const char* buffer, size_t size ). More...

virtual size_t	write (const uint8_t *buffer, size_t size)
	Write a given number of bytes from a buffer to the output stream. This implements the pure virtual function Writer::write( const uint8_t* buffer, size_t size ). More...

virtual void	flush ()
	Flush the output stream. When this function returns, all previously written data will have been transmitted through the underlying output stream. This implements the pure virtual function Writer::flush().

virtual int	read ()
	Read and remove the next byte from the input stream. This implements the pure virtual function Reader::read(). More...

virtual int	peek ()
	Examine the next byte from the input stream, without removing it. This implements the pure virtual function Reader::peek(). More...

virtual bool	available ()
	Determine if data is available in the input stream. This implements the pure virtual function Reader::available(). More...

size_t	print (const char *str, bool addLn=false)
	Print a null-terminated string to the output stream, with or without adding a new line character at the end. More...

size_t	print (const uint8_t *buf, size_t size, bool addLn=false)
	Print a number of bytes to the output stream, with or without adding a new line character at the end. More...

size_t	print (char c, bool addLn=false)
	Print a single character to the output stream, with or without adding a new line character at the end. More...

size_t	print (int8_t n, int base=kDec, bool addLn=false)
	Print an 8-bit integer to the output stream, with or without adding a new line character at the end. More...

size_t	print (uint8_t n, int base=kDec, bool addLn=false)
	Print an 8-bit unsigned integer to the output stream, with or without adding a new line character at the end. More...

size_t	print (int n, int base=kDec, bool addLn=false)
	Print an integer to the output stream, with or without adding a new line character at the end. More...

size_t	print (unsigned int n, int base=kDec, bool addLn=false)
	Print an unsigned integer to the output stream, with or without adding a new line character at the end. More...

size_t	print (long n, int base=kDec, bool addLn=false)
	Print a long integer to the output stream, with or without adding a new line character at the end. More...

size_t	print (unsigned long n, int base=kDec, bool addLn=false)
	Print an unsigned long integer to the output stream, with or without adding a new line character at the end. More...

size_t	print (double d, int digits=2, bool addLn=false)
	Print a floating point number to the output stream, with or without adding a new line character at the end. More...

size_t	println (const char *str)
	Print a null-terminated string to the output stream, adding a new line character at the end. More...

size_t	println (const uint8_t *buf, size_t size)
	Print a number of bytes to the output stream, adding a new line character at the end. More...

size_t	println (char c)
	Print a single character to the output stream, adding a new line character at the end. More...

size_t	println (int8_t n, int base=kDec)
	Print an 8-bit integer to the output stream, adding a new line character at the end. More...

size_t	println (uint8_t n, int base=kDec)
	Print an 8-bit unsigned integer to the output stream, adding a new line character at the end. More...

size_t	println (int n, int base=kDec)
	Print an integer to the output stream, adding a new line character at the end. More...

size_t	println (unsigned int n, int base=kDec)
	Print an unsigned integer to the output stream, adding a new line character at the end. More...

size_t	println (long n, int base=kDec)
	Print a long integer to the output stream, adding a new line character at the end. More...

size_t	println (unsigned long n, int base=kDec)
	Print an unsigned long integer to the output stream, adding a new line character at the end. More...

size_t	println (double d, int digits=2)
	Print a floating point number to the output stream, adding a new line character at the end. More...

size_t	println ()
	Print a new line to the output stream.

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

bool	find (const char *target)
	Read data from the input 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)
	Read data from the stream until the target string is found, or the terminator string is found, or the function times out. More...

bool	findUntil (const char target, size_t targetLen, const char terminate, size_t termLen)
	Read data from the stream until the target string of given length is found, or the terminator string of given length is found, or the function times out. More...

bool	readLong (long *result)
	Return the first valid long integer value from the stream. More...

bool	readLong (long *result, char skipChar)
	Return the first valid long integer value from the stream, ignoring selected characters. More...

bool	readFloat (float *result)
	Return the first valid float value from the stream. More...

bool	readFloat (float *result, char skipChar)
	Return the first valid float value from the stream, ignoring selected characters. More...

size_t	readBytes (char *buffer, size_t length)
	Read characters from the input stream into a buffer, terminating if length characters have been read or the function times out. The result is NOT null-termimated. More...

size_t	readBytes (uint8_t *buffer, size_t length)
	Read bytes (uint8_t) from the input stream into a buffer, terminating if length bytes have been read or the function times out. More...

size_t	readBytesUntil (char terminator, char *buffer, size_t length)
	Read characters from the input stream into a buffer, terminating when the terminator charactor is encountered, or if length characters have been read, or if the function times out. The result is NOT null-terminated. More...

size_t	readBytesUntil (uint8_t terminator, uint8_t *buffer, size_t length)
	Read bytes (uint8_t) from the input stream into a buffer, terminating when the terminator byte is encountered, or if length bytes have been read, or if the function times out. More...

size_t	readLine (char *buffer, size_t length)
	Read characters from the input stream into a buffer, until it reaches EOL, or if length characters have been read, or if it times out. The result IS null-termimated. More...

void	consumeWhiteSpace ()
	Consumes whitespace characters until the first non-whitespace character is encountered or the function times out.

Detailed Description

Provides a high-end interface to serial communications using USART3.

The functions in this class are buffered for both input and output and operate using interrupts associated with USART3. This means the write functions return immediately after queuing data in the output buffer for transmission and the transmission happens asynchronously, using dedicated USART3 hardware. Similarly, data is received asynchronously and placed into the read buffer.

The read and write buffers are both ring buffers. If you try to queue more data than the transmit buffer can hold, the write functions will block until there is room in the buffer (as a result of data being transmitted). The read buffer, however, will overwrite if it gets full. You must clear the read buffer by actually reading the data regularly when receiving significant amounts of data.

Member Enumeration Documentation

§ IntegerOutputBase

enum Writer::IntegerOutputBase

inherited

An enumeration that defines the number that will be used as the base for representing integer quantities as a string of characters.

Enumerator
kBin	Produce a binary representation of integers (e.g., 11 is output as 0b1011)
kOct	Produce an octal representation of integers (e.g, 11 is output as 013)
kDec	Produce a decimal representation of integers (e.g., 11 is output as 11.
kHex	Produce a hexadecimal representation of integers (e.g., 11 is output as 0x0b)

Member Function Documentation

§ available()

bool Serial3::available ( )

virtual

Determine if data is available in the input stream. This implements the pure virtual function Reader::available().

Returns: True if data is available in the stream; false if not.

Implements Reader.

§ find() [1/2]

bool Reader::find ( const char * target )

inlineinherited

Read data from the input stream until the target string is found.

target is the string the function seeks in the input stream.

Returns: true if target string is found before timeout, false otherwise.

§ find() [2/2]

bool Reader::find	(	const char *	target,
		size_t	length
	)

inlineinherited

Read data from the stream until the target string of given length is found.

target is a string, the first length bytes of which the function seeks in the input stream.
length is the number of bytes of the string to use for comparison.

Returns: true if target string of given length is found, false if the function times out before finding the target string.

§ findUntil() [1/2]

bool Reader::findUntil	(	const char *	target,
		const char *	terminator
	)

inherited

Read data from the stream until the target string is found, or the terminator string is found, or the function times out.

This function is like find() but the search ends if the terminator string is found first.

target is the string the function seeks in the input stream.
terminator is the string that stops the search.

Returns: true if target string is found before the terminator is encountered and before the function times out; false otherwise.

§ findUntil() [2/2]

bool Reader::findUntil	(	const char *	target,
		size_t	targetLen,
		const char *	terminate,
		size_t	termLen
	)

inherited

Read data from the stream until the target string of given length is found, or the terminator string of given length is found, or the function times out.

This function is like find() but the search ends if the terminator string is found first.

target is the string the function seeks in the input stream.
targetLen is the number of bytes in target that the function seeks in the input stream.
terminator is the string that stops the search.
termLen is the number of bytes in the terminator that

Returns: true if target string is found before the terminator is encountered and before the function times out; false otherwise.

§ peek()

int Serial3::peek ( )

virtual

Examine the next byte from the input stream, without removing it. This implements the pure virtual function Reader::peek().

Returns: the next byte, or -1 if there is nothing to read in the input stream before timeout expires.

Implements Reader.

§ print() [1/10]

size_t Writer::print	(	const char *	str,
		bool	addLn = `false`
	)

inherited

Print a null-terminated string to the output stream, with or without adding a new line character at the end.

str is the null-terminated string to output.
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [2/10]

size_t Writer::print	(	const uint8_t *	buf,
		size_t	size,
		bool	addLn = `false`
	)

inherited

Print a number of bytes to the output stream, with or without adding a new line character at the end.

buf is the buffer containing bytes to output.
size is the number of bytes from the buffer to output.
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [3/10]

size_t Writer::print	(	char	c,
		bool	addLn = `false`
	)

inherited

Print a single character to the output stream, with or without adding a new line character at the end.

c is the character to output.
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [4/10]

size_t Writer::print	(	int8_t	n,
		int	base = `kDec`,
		bool	addLn = `false`
	)

inherited

Print an 8-bit integer to the output stream, with or without adding a new line character at the end.

n is the integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [5/10]

size_t Writer::print	(	uint8_t	n,
		int	base = `kDec`,
		bool	addLn = `false`
	)

inlineinherited

Print an 8-bit unsigned integer to the output stream, with or without adding a new line character at the end.

n is the integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [6/10]

size_t Writer::print	(	int	n,
		int	base = `kDec`,
		bool	addLn = `false`
	)

inherited

Print an integer to the output stream, with or without adding a new line character at the end.

n is the integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [7/10]

size_t Writer::print	(	unsigned int	n,
		int	base = `kDec`,
		bool	addLn = `false`
	)

inlineinherited

Print an unsigned integer to the output stream, with or without adding a new line character at the end.

n is the unsigned integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [8/10]

size_t Writer::print	(	long	n,
		int	base = `kDec`,
		bool	addLn = `false`
	)

inherited

Print a long integer to the output stream, with or without adding a new line character at the end.

n is the long integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [9/10]

size_t Writer::print	(	unsigned long	n,
		int	base = `kDec`,
		bool	addLn = `false`
	)

inherited

Print an unsigned long integer to the output stream, with or without adding a new line character at the end.

n is the unsigned long integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ print() [10/10]

size_t Writer::print	(	double	d,
		int	digits = `2`,
		bool	addLn = `false`
	)

inherited

Print a floating point number to the output stream, with or without adding a new line character at the end.

d is the floating point number to output.
digits is the number of decimal digits to output; the default is 2.
addLn if true, a new line character is added at the end of the output; the default is false.

Returns: the number of bytes sent to the output stream.

§ println() [1/10]

size_t Writer::println ( const char * str )

inlineinherited

Print a null-terminated string to the output stream, adding a new line character at the end.

str is the null-terminated string to output.

Returns: the number of bytes sent to the output stream.

§ println() [2/10]

size_t Writer::println	(	const uint8_t *	buf,
		size_t	size
	)

inlineinherited

Print a number of bytes to the output stream, adding a new line character at the end.

buf is the buffer containing bytes to output.
size is the number of bytes from the buffer to output.

Returns: the number of bytes sent to the output stream.

§ println() [3/10]

size_t Writer::println ( char c )

inlineinherited

Print a single character to the output stream, adding a new line character at the end.

c is the character to output.

Returns: the number of bytes sent to the output stream.

§ println() [4/10]

size_t Writer::println	(	int8_t	n,
		int	base = `kDec`
	)

inlineinherited

Print an 8-bit integer to the output stream, adding a new line character at the end.

n is the integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).

Returns: the number of bytes sent to the output stream.

§ println() [5/10]

size_t Writer::println	(	uint8_t	n,
		int	base = `kDec`
	)

inlineinherited

Print an 8-bit unsigned integer to the output stream, adding a new line character at the end.

n is the unsigned integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).

Returns: the number of bytes sent to the output stream.

§ println() [6/10]

size_t Writer::println	(	int	n,
		int	base = `kDec`
	)

inlineinherited

Print an integer to the output stream, adding a new line character at the end.

n is the integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).

Returns: the number of bytes sent to the output stream.

§ println() [7/10]

size_t Writer::println	(	unsigned int	n,
		int	base = `kDec`
	)

inlineinherited

Print an unsigned integer to the output stream, adding a new line character at the end.

n is the unsigned integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).

Returns: the number of bytes sent to the output stream.

§ println() [8/10]

size_t Writer::println	(	long	n,
		int	base = `kDec`
	)

inlineinherited

Print a long integer to the output stream, adding a new line character at the end.

n is the long integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).

Returns: the number of bytes sent to the output stream.

§ println() [9/10]

size_t Writer::println	(	unsigned long	n,
		int	base = `kDec`
	)

inlineinherited

Print an unsigned long integer to the output stream, adding a new line character at the end.

n is the unsigned long integer to output.
base is the base used to represent the number; should be one of IntegerOutputBase; defaults to decimal representation (kDec).

Returns: the number of bytes sent to the output stream.

§ println() [10/10]

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

inlineinherited

Print a floating point number to the output stream, adding a new line character at the end.

d is the flaoting point number to output.
digits is the number of decimal digits to output; the default is 2.

Returns: the number of bytes sent to the output stream.

§ read()

int Serial3::read ( )

virtual

Read and remove the next byte from the input stream. This implements the pure virtual function Reader::read().

Returns: the next byte, or -1 if there is nothing to read in the input stream before timeout expires.

Implements Reader.

§ readBytes() [1/2]

size_t Reader::readBytes	(	char *	buffer,
		size_t	length
	)

inherited

Read characters from the input stream into a buffer, terminating if length characters have been read or the function times out. The result is NOT null-termimated.

buffer a pointer to where the characters read will be stored.
length the maximum number of characters to read.

Returns: the number of characters placed in the buffer (0 means no data were read prior to timeout).

§ readBytes() [2/2]

size_t Reader::readBytes	(	uint8_t *	buffer,
		size_t	length
	)

inlineinherited

Read bytes (uint8_t) from the input stream into a buffer, terminating if length bytes have been read or the function times out.

buffer a pointer to where the bytes read will be stored.
length the maximum number of bytes to read.

Returns: the number of bytes placed in the buffer (0 means no data were read prior to timeout).

§ readBytesUntil() [1/2]

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

inherited

Read characters from the input stream into a buffer, terminating when the terminator charactor is encountered, or if length characters have been read, or if the function times out. The result is NOT null-terminated.

terminator a character that when encountered causes the function to return.
buffer a pointer to where the characters read will be stored.
length the maximum number of characters to read.

Returns: the number of characters placed in the buffer (0 means no data were read prior to timeout or detecting the terminator character).

§ readBytesUntil() [2/2]

size_t Reader::readBytesUntil	(	uint8_t	terminator,
		uint8_t *	buffer,
		size_t	length
	)

inlineinherited

Read bytes (uint8_t) from the input stream into a buffer, terminating when the terminator byte is encountered, or if length bytes have been read, or if the function times out.

terminator a byte that when encountered causes the function to return.
buffer a pointer to where the bytes read will be stored.
length the maximum number of bytes to read.

Returns: the number of bytes placed in the buffer (0 means no data were read prior to timeout or detecting the terminator character).

§ readFloat() [1/2]

bool Reader::readFloat ( float * result )

inherited

Return the first valid float value from the stream.

Initial characters that are not digits (or the minus sign) are skipped; the float is terminated by the first character that is not a digit.

result is a pointer to where the float will be stored.

Returns: true if a valid float is found prior to timeout; false otherwise.

§ readFloat() [2/2]

bool Reader::readFloat	(	float *	result,
		char	skipChar
	)

inherited

Return the first valid float value from the stream, ignoring selected characters.

Initial characters that are not digits (or the minus sign) are skipped; the float is terminated by the first character that is not a digit and is not one of the skip characters. This allows format characters (typically commas) to be ignored on input.

result is a pointer to where the float will be stored.
skipChar is a character that will be ignored on input.

Returns: true if a valid float is found prior to timeout; false otherwise.

§ readLine()

size_t Reader::readLine	(	char *	buffer,
		size_t	length
	)

inherited

Read characters from the input stream into a buffer, until it reaches EOL, or if length characters have been read, or if it times out. The result IS null-termimated.

buffer a pointer to where the characters read will be stored.
length the maximum number of characters to read.

Returns: the number of characters placed in the buffer (0 means no data were read prior to timeout or detecting EOL).

§ readLong() [1/2]

bool Reader::readLong ( long * result )

inherited

Return the first valid long integer value from the stream.

Initial characters that are not digits (or the minus sign) are skipped; the integer is terminated by the first character that is not a digit.

result is a pointer to where the long integer will be stored.

Returns: true if a valid integer is found prior to timeout; false otherwise.

§ readLong() [2/2]

bool Reader::readLong	(	long *	result,
		char	skipChar
	)

inherited

Return the first valid long integer value from the stream, ignoring selected characters.

Initial characters that are not digits (or the minus sign) are skipped; the integer is terminated by the first character that is not a digit and is not one of the skip characters. This allows format characters (typically commas) to be ignored on input.

result is a pointer to where the long integer will be stored.
skipChar is a character that will be ignored on input.

Returns: true if a valid long integer is found prior to timeout; false otherwise.

§ setTimeout()

void Reader::setTimeout ( unsigned long milliseconds )

inlineinherited

Sets maximum milliseconds to wait for stream data, default is 1 second.

milliseconds the length of the timeout period in milliseconds.

§ start()

void Serial3::start	(	unsigned long	baudRate,
		UsartSerialConfiguration	config = `kSerial_8N1`
	)

inline

Configure the hardware for two-way serial communications, including turning on associated interrupts. You must call this function before reading from or writing to Serial3 on USART3.

baudRate the baud rate for the communications, usually one of the following values: 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, or 115200 (although other values below can be specified).

config sets the configuration in term of data bits, parity, and stop bits. If omitted, the default is 8 data bits, no parity, and 1 stop bit.

§ stop()

void Serial3::stop ( )

inline

Stops buffered serial communications using Serial3 on USART3 by deconfiguring the hardware and turning off interrupts.

After calling this function, Arduino pins 0 and 1 are released and available for use as ordinary digital pins.

If you want to use Serial3 again for communications, you must call start() again.

§ write() [1/4]

size_t Serial3::write ( char c )

virtual

Write a single character to the output stream. This implements the pure virtual function Writer::write( char c ).

the character to be written.

Returns: the number of bytes written.

Implements Writer.

§ write() [2/4]

size_t Serial3::write ( const char * str )

virtual

Write a null-terminated string to the output stream. This implements the pure virtual function Writer::write( char* str ).

str the string to be written.

Returns: the number of bytes written.

Implements Writer.

§ write() [3/4]

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

virtual

Write a given number of characters from a buffer to the output stream. This implements the pure virtual function Writer::write( const char* buffer, size_t size ).

buffer the buffer of characters to write.
size the number of characters to write

Returns: the number of bytes written.

Implements Writer.

§ write() [4/4]

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

virtual

Write a given number of bytes from a buffer to the output stream. This implements the pure virtual function Writer::write( const uint8_t* buffer, size_t size ).

buffer the buffer of bytes to write.
size the number of bytes to write

Returns: the number of bytes written.

Implements Writer.

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

USART3.h
USART3.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

§ IntegerOutputBase

Member Function Documentation

§ available()

§ find() [1/2]

§ find() [2/2]

§ findUntil() [1/2]

§ findUntil() [2/2]

§ peek()

§ print() [1/10]

§ print() [2/10]

§ print() [3/10]

§ print() [4/10]

§ print() [5/10]

§ print() [6/10]

§ print() [7/10]

§ print() [8/10]

§ print() [9/10]

§ print() [10/10]

§ println() [1/10]

§ println() [2/10]

§ println() [3/10]

§ println() [4/10]

§ println() [5/10]

§ println() [6/10]

§ println() [7/10]

§ println() [8/10]

§ println() [9/10]

§ println() [10/10]

§ read()

§ readBytes() [1/2]

§ readBytes() [2/2]

§ readBytesUntil() [1/2]

§ readBytesUntil() [2/2]

§ readFloat() [1/2]

§ readFloat() [2/2]

§ readLine()

§ readLong() [1/2]

§ readLong() [2/2]

§ setTimeout()

§ start()

§ stop()

§ write() [1/4]

§ write() [2/4]

§ write() [3/4]

§ write() [4/4]