The BufferedSerial class mediates access to an underlying serial device. More...

#include <buffered-serial.h>

Public Member Functions
	BufferedSerial ()
	Create a new BufferedSerial object, and initialise the underlying serial port.

void	init (void)
	Initialise the buffered-serial object, after the program is under way. More...

void	logprintf (PGM_P format,...)
	The logprintf function supports a simple printf-like syntax for writing data to the Serial port. More...

void	logvprintf (PGM_P format, va_list ap)
	The logvprintf is the varargs companion to the logprintf function. More...

int	putchar (const int)
	Append a single byte to the output.

int	read_items_read_char (void)
	Read a character from Serial, and return the number of bytes actually read. More...

InputItem *	read_items_get (int *n)
	Retrieve items from the Serial input. More...

void	read_items_reset (void)
	Reset the buffer of read items. More...

bool	read_available (void)
	Return true if there is at least one byte available to be read.

int	count_discarded (void)
	Return the number of bytes discarded since the last call to this method. More...

Detailed Description

The BufferedSerial class mediates access to an underlying serial device.

For input, it provides the following methods to support reading items from the serial bus.

int read_items_read_char(void);
InputItem* read_items_get(int* n);
void read_items_reset(void);

Whenever read_available() is true, call read_items_read_char: this takes one byte off the bus, and cumulatively parses these bytes into an array of arguments of type character, integer or float. Before a complete line is available (terminated by \n), the function read_items_get returns NULL. After a complete line is available, read_items_get will return non-NULL, providing a pointer to the array of InputItem structs, and it will stop accumulating bytes from the bus. Subsequent calls to the function will return the same non-NULL pointer. Call read_items_reset to clear this, and start accumulating bytes again.

These functions will parse a sequence of single characters /[a-zA-Z]/, integers /-?[0-9]+/ and floats /-?[0-9]*\.[0-9]/ from the Serial port, separated by any other characters, which are ignored. Thus aB123;4. .5 \n parses as ['a', 'B', 123, 4.0, 0.5]

For output, there are the function

void logprintf(PGM_P format, ...);

This formats a string to an internal circular buffer, which the underlying Serial library sends to the output on an interrupt-driven schedule.

If the output buffer becomes full, extra writes to it are discarded if the string starts with a # character. The method count_discarded returns the number of bytes thus discarded since the last call to the method.

See also: read_items_read_char; read_items_get; read_items_reset; logprintf

Member Function Documentation

int BufferedSerial::count_discarded ( void )

Return the number of bytes discarded since the last call to this method.

If logprintf fills up the buffer, extra bytes are silently discarded.

void BufferedSerial::init ( void )

Initialise the buffered-serial object, after the program is under way.

This can't be done at constructor time (it's not completely clear why not, but it's plausibly because there's some run-time initialisation that the Arduino runtime does before calling setup()).

void BufferedSerial::logprintf	(	PGM_P	format,
			...
	)

The logprintf function supports a simple printf-like syntax for writing data to the Serial port.

The format string must be in program memory – that is, as an argument to the PSTR macro: PSTR("format").

The format specifiers are:

spec	explanation
%%	print out a percent sign
c	a character; non-printing characters are displayed as hex
l	a long int (such as the return from millis()
d	an ordinary int, printed in decimal
x	an int, printed in hex
s	a PSTR string
g	a float
G	a float, but with more decimal places printed

For convenience, the function writes a newline to the port at the end of the format string. If you wish to suppress this, then include the 'format specifier' %| at the end of the string.

There is minimal error-checking on the format specifier.

void BufferedSerial::logvprintf	(	PGM_P	format,
		va_list	ap
	)

The logvprintf is the varargs companion to the logprintf function.

Once a varargs argument pointer is set up, it can be passed to this function for handling. The logprintf function is equivalent to:

void Util::logprintf(PGM_P format, ...)
{
    va_list ap;

    va_start(ap, format);
    logvprintf(format, ap);
    va_end(ap);
}

See also: logprintf

InputItem * BufferedSerial::read_items_get ( int * n )

Retrieve items from the Serial input.

Returns: a pointer to the array of items, or NULL if a complete line has not yet been read

int BufferedSerial::read_items_read_char ( void )

Read a character from Serial, and return the number of bytes actually read.

See also: read_items_get

void BufferedSerial::read_items_reset ( void )

Reset the buffer of read items.

See also: read_items_get

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

buffered-serial.h
buffered-serial.cpp

Public Member Functions

Detailed Description

Member Function Documentation