This library provides a collection of functions for communicating with text devices such as SimpleIDE Terminal, serial peripheral devices, and even VGA displays. Libraries like serial, fdserial, and vgatext return pointer/identifiers that can be used with this library's dprint, dscan, and write/read function parameters that have text_t types. The identifier allows the application's code to specify which connection to use for sending and receiving formatted text. More...

#include <propeller.h>
#include "serial.h"
#include <stdarg.h>

Data Structures
struct	text_struct
	Structure that contains data used by simple text device libraries. More...

Typedefs
typedef struct text_struct	text_t
	Structure that contains data used by simple text device libraries.
typedef text_t	terminal

Functions
int	print (const char *format,...) __attribute__((format(printf
	Print format "..." args to the default simple terminal device. The output is limited to 256 bytes.
int int	scan (const char *fmt,...) __attribute__((format(printf
	Convert formatted simple terminal input to the "..." args. The input is limited to 256 bytes.
int int int	sprint (char buffer, const char format,...) __attribute__((format(printf
	Print format "..." args to the output buffer. The output buffer must be big enough for the output.
int int int int	sscan (const char buffer, const char fmt,...) __attribute__((format(printf
	Convert formatted buffer to the "..." args.
Print/Scan for Device Communication
int	dprint (text_t device, const char format,...) __attribute__((format(printf
	Print format "..." args to the device The output is limited to 256 bytes.
int int	dscan (text_t device, const char fmt,...) __attribute__((format(printf
	Convert formatted device input to the "..." args. The input is limited to 256 bytes.
Integer-Only Versions
For reduced program sizes if no floating point values are printed/scanned.
int	printi (const char *format,...) __attribute__((format(printf
	Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.
int int	scani (const char *fmt,...) __attribute__((format(printf
	Convert formatted simple terminal input to the "..." args. This version does not provide floating point conversions. The input is limited to 256 bytes.
int int int	dprinti (text_t device, const char format,...) __attribute__((format(printf
	Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.
int int int int	dscani (text_t device, const char fmt,...) __attribute__((format(printf
	Convert formatted device input to the "..." args. This version does not provide floating point conversions. The input is limited to 256 bytes.
int int int int int	sprinti (char buffer, const char format,...) __attribute__((format(printf
	Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.
int int int int int int	sscani (const char buffer, const char fmt,...) __attribute__((format(printf
	Convert formatted buffer to the "..." args. This version does not provide floating point conversions.
Output to Terminal
void	putChar (char c)
	Print a char to the debug port.
int	putStr (const char *str)
	Print string to the debug port.
void	putDec (int value)
	Print string representation of a decimal number to the debug port.
void	putFloat (float value)
	Print string representation of a 32 bit floating point number to the debug port.
void	putBin (int value)
	Print string representation of a binary number to the debug port.
void	putHex (int value)
	Print string representation of a hexadecimal number to the debug port.
int	putStrLen (char *str, int width)
	Send a string with a certain number of characters.
void	putDecLen (int value, int width)
	Print string representation of a decimal number to the debug port.
void	putFloatPrecision (float value, int width, int precision)
	Print string representation of a 32 bit floating point number to the debug port with a fixed number of digits.
void	putBinLen (int value, int digits)
	Print string representation of a binary number to debug port with a fixed number of digits.
void	putHexLen (int value, int digits)
	Print string representation of a hexadecimal number to the debug port with a fixed number of digits.
int	putln (const char *str)
	Print string + new line on the transmit debug port.
int	putLine (const char *str)
	Print string + new line on the transmit debug port. This is an alias of putln.
Input from Terminal
int	getBin (void)
	Get binary number from the debug port.
int	getChar (void)
	Get char from the debug port.
int	getDec (void)
	Get decimal number from the debug port.
float	getFloat (void)
	Get floating point number from the debug port.
int	getHex (void)
	Get hexadecimal number from the debug port.
char *	getStr (char *buffer, int max)
	Get string of chars from the debug port.
Output to Device
void	writeChar (text_t *device, char c)
	Send a character to the device.
int	writeStr (text_t device, char str)
	Send a string to the device.
void	writeDec (text_t *device, int value)
	Print string representation of a decimal number to output.
void	writeFloat (text_t *device, float value)
	Print string representation of a 32 bit floating point number to device.
void	writeBin (text_t *device, int value)
	Print string representation of a binary number to the receive device.
void	writeHex (text_t *device, int value)
	Print string representation of a hexadecimal number to output device.
int	writeStrLen (text_t device, char str, int width)
	Send a string to the device.
void	writeDecLen (text_t *device, int value, int width)
	Print string representation of a decimal number to output device with a fixed number of digits.
void	writeFloatPrecision (text_t *device, float value, int width, int precision)
	Print string representation of a 32 bit floating point number to device with a certain number of decimal point digits.
void	writeBinLen (text_t *device, int value, int digits)
	Print string representation of a binary number to output with a fixed number of digits.
void	writeHexLen (text_t *device, int value, int digits)
	Print string representation of a hexadecimal number to output device with a fixed number of digits.
int	writeLine (text_t device, char str)
	Send a string + new line to the device.
Input from Device
int	readChar (text_t *device)
	Get char from the device.
char *	readStr (text_t device, char buffer, int max)
	Get string of chars from the device.
int	readDec (text_t *device)
	Get decimal number from the device.
float	readFloat (text_t *device)
	Get floating point number from the device.
int	readBin (text_t *device)
	Get binary number from the device.
int	readHex (text_t *device)
	Get hexadecimal number from the device.
For Passing Terminal Control between Cogs and/or Devices
terminal *	simpleterm_open (void)
	Reopens the SimpleIDE Terminal connection if it was closed previously. The SimpleIDE Terminal connection transmits on P30 and receives on P31 at 115200 bps. The port is a simple serial driver running in the same cog, and does not buffer bytes.
void	simpleterm_close (void)
	Closes the SimpleIDE Terminal connection in one cog so that it can be opened in another cog with simpleterm_open, fdserial_open(30, 31, 0, 115200), or some other driver.
terminal *	simpleterm_reopen (int rxpin, int txpin, int mode, int baud)
	Closes and the simple terminal connection, and reopens it in the calling cog. Depending on the parameters used, it can also be used to switch from one terminal device to another.
terminal *	simpleterm_pointer (void)
	Get default device pointer to SimpleIDE Terminal.

Detailed Description

This library provides a collection of functions for communicating with text devices such as SimpleIDE Terminal, serial peripheral devices, and even VGA displays. Libraries like serial, fdserial, and vgatext return pointer/identifiers that can be used with this library's dprint, dscan, and write/read function parameters that have text_t types. The identifier allows the application's code to specify which connection to use for sending and receiving formatted text.

Author: Steve Denson

Copyright: Copyright (C) Parallax, Inc. 2014. All Rights MIT Licensed.

Features:

Generic IO devices support with reduced code size
Supports IO devices with rxChar/txChar functions.
Contains 2 built-in device drivers - fdserial and simpleserial.
Can get and print decimal, binary, float, hex, char, and string.
Supports print format values to buffer comparable to sprintf (printBuffFormat and sprint).
Supports format values from buffer comparable to sscanf (scanBuffFormat and sscan).

Core Usage: Functions in this library do not use any additional cores; however, the device driver library that returns a text_t pointer for use with this library might. For example, fdserial and vgatext each take launch a core. Check the device driver library's documentation for details.

Memory Models: Use with CMM or LMM.

Version: 0.99.1 Correct scan function %s formatting flag bugs.; 0.99 Digits versions of put/get and write/read added for transmitting and receiving values with fixed numbers of digits. Floating point output functions updated to handle nan (not a number) and +/- inf (infinity). printi, dprinti, scani, dscani, sprinti, sscani functions added for supporting non-floating point with less program space. functions with Len in their names added for transmitting strings and values represented with a fixed number of characters.

Typedef Documentation

typedef text_t terminal

By default the terminal will use simple serial for input/output It can be overloaded.

Function Documentation

int dprint	(	text_t *	device,
		const char *	format,
			...
	)

Print format "..." args to the device The output is limited to 256 bytes.

Note: See print for format specifiers.

Parameters

*device	Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
format	C printf comparable format string.
...	Arguments to use with the format string.

Returns: Number of bytes placed into the buffer.

int int int dprinti	(	text_t *	device,
		const char *	format,
			...
	)

Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.

Note: See print for format specifiers except f.

Parameters

*device	Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
format	C printf comparable format string.
...	Arguments to use with the format string.

Returns: Number of bytes placed into the buffer.

int int dscan	(	text_t *	device,
		const char *	fmt,
			...
	)

Convert formatted device input to the "..." args. The input is limited to 256 bytes.

Note: See scan for format specifiers.

Parameters

*device	Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
*fmt	C printf comparable format string.
...	Arguments where output will go and must be pointers.

Returns: Number of bytes placed into the buffer.

int int int int dscani	(	text_t *	device,
		const char *	fmt,
			...
	)

Convert formatted device input to the "..." args. This version does not provide floating point conversions. The input is limited to 256 bytes.

Note: See scan for format specifiers.

Parameters

*device	Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
*fmt	C printf comparable format string.
...	Arguments where output will go and must be pointers.

Returns: Number of bytes placed into the buffer.

int getBin ( void )

Get binary number from the debug port.

Returns: Value received.

int getChar ( void )

Get char from the debug port.

Returns: Character received as an integer.

int getDec ( void )

Get decimal number from the debug port.

Returns: Value received.

float getFloat ( void )

Get floating point number from the debug port.

Returns: Value received.

int getHex ( void )

Get hexadecimal number from the debug port.

Returns: Value received.

char* getStr	(	char *	buffer,
		int	max
	)

Get string of chars from the debug port.

Parameters

*buffer	array of chars with enough elements to hold the input string plus 2 null terminators.
max	Maximum size to read and should be less or equal buffer size.

Returns: Pointer to string received.

int print	(	const char *	format,
			...
	)

Print format "..." args to the default simple terminal device. The output is limited to 256 bytes.

Format specifiers for print dprint, and sprint:

%% Prints % sign to the output.

b Prints binary representation of an int parameter. Note: b is not an ANSI standard format specifier.

c Prints char representation of a char parameter.

d Prints decimal integer representation of an int parameter.

f Prints floating point representation of a float parameter.

s Prints string representation of a char* parameter.

u Prints unsigned integer representation of an unsigned int parameter.

x Prints hexadecimal integer representation of an int parameter.

Width and precision n.p cause n integer digits of a float to print, and p digits to the right of the decimal to print.

Parameters

format	C printf comparable format string.
...	Arguments to use with the format string.

Returns: Number of bytes placed into the buffer.

int printi	(	const char *	format,
			...
	)

Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.

Note: See print for format specifiers except f.

Parameters

format	C printf comparable format string.
...	Arguments to use with the format string.

Returns: Number of bytes placed into the buffer.

void putBin ( int value )

Print string representation of a binary number to the debug port.

Parameters

value Number to print.

void putBinLen	(	int	value,
		int	digits
	)

Print string representation of a binary number to debug port with a fixed number of digits.

Parameters

value	Number to print.
digits	Number of characters to print.

void putChar ( char c )

Print a char to the debug port.

Parameters

c	Char to send.

void putDec ( int value )

Print string representation of a decimal number to the debug port.

Parameters

value Number to print.

void putDecLen	(	int	value,
		int	width
	)

Print string representation of a decimal number to the debug port.

Parameters

value	Number to print.
width	Number of characters to print padded by zeroes.

void putFloat ( float value )

Print string representation of a 32 bit floating point number to the debug port.

Parameters

value Number to print.

void putFloatPrecision	(	float	value,
		int	width,
		int	precision
	)

Print string representation of a 32 bit floating point number to the debug port with a fixed number of digits.

Parameters

value	Number to print.
width	Number of characters to print.
precision	Number of decimal point digits to print.

void putHex ( int value )

Print string representation of a hexadecimal number to the debug port.

Parameters

value Number to print.

void putHexLen	(	int	value,
		int	digits
	)

Print string representation of a hexadecimal number to the debug port with a fixed number of digits.

Parameters

value	Number to print.
digits	Number of hexadecimal characters to print padded by zeroes.

int putLine ( const char * str )

Print string + new line on the transmit debug port. This is an alias of putln.

Parameters

*str	Null terminated string to send.

int putln ( const char * str )

Print string + new line on the transmit debug port.

Parameters

*str	Null terminated string to send.

int putStr ( const char * str )

Print string to the debug port.

Parameters

*str	Null terminated string to send.

int putStrLen	(	char *	str,
		int	width
	)

Send a string with a certain number of characters.

Parameters

str	Null terminated string to send.
width	Number of characters to print padded by spaces.

int readBin ( text_t * device )

Get binary number from the device.

Parameters