SFBPrint.h File Reference

Support for basic formatted printing. More...

#include "SFBConstants.h"
#include "SFBAlarm.h"
#include "SFBReactor.h"
#include "SFBFrame.h"

Include dependency graph for SFBPrint.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  FacePrinter
 A FacePrinter is capable of performing low-level printing operations to some assigned (physical or 'virtual') face. More...

Functions

void print (const char *str)
 Same as facePrint(u8 face, const char * str) with face set to ALL_FACES.
void print (const u8 *str, u32 len)
 Same as facePrint(u8 face, const u8 * str,u32 len) with face set to ALL_FACES.
void print (int decimal)
 Same as facePrint(u8 face, int decimal) with face set to ALL_FACES.
void print (unsigned int decimal)
 Same as facePrint(u8 face, unsigned long decimal) with face set to ALL_FACES.
void print (long decimal)
 Same as facePrint(u8 face, long decimal) with face set to ALL_FACES.
void print (unsigned long decimal)
 Same as facePrint(u8 face, unsigned long decimal) with face set to ALL_FACES.
void print (long decimal, int code)
 Same as facePrint(u8 face, unsigned long decimal, int code) with face set to ALL_FACES.
void print (double val)
 Same as facePrint(u8 face, double val) with face set to ALL_FACES.
void printFace ()
 Same as facePrintFace(u8 face) with face set to ALL_FACES.
void println ()
 Same as facePrintln(u8 face) with face set to ALL_FACES.
void println (const char *str)
 Same as facePrintln(u8 face, const char * str) with face set to ALL_FACES.
void println (const u8 *str, u32 len)
 Same as facePrintln(u8 face, const u8 * str,u32 len) with face set to ALL_FACES.
void println (int decimal)
 Same as facePrintln(u8 face, int decimal) with face set to ALL_FACES.
void println (unsigned int decimal)
 Same as facePrintln(u8 face, unsigned long decimal) with face set to ALL_FACES.
void println (long decimal)
 Same as facePrintln(u8 face, long decimal) with face set to ALL_FACES.
void println (unsigned long decimal)
 Same as facePrint(u8 face, unsigned long decimal) with face set to ALL_FACES.
void println (long decimal, int code)
 Same as facePrintln(u8 face, unsigned long decimal, int code) with face set to ALL_FACES.
void println (double val)
 Same as facePrint(u8 face, double val) with face set to ALL_FACES.
void printlnCheckByte ()
 Same as facePrintlnCheckByte() with face set to ALL_FACES.
void facePrint (u8 face, const char *str)
 Print the contents of a null-terminated string to the current xmit packet of face.
void facePrint (u8 face, const u8 *str, u32 len)
 Print str, an array of bytes of length len, to the current xmit packet of face.
void facePrint (u8 face, int decimal)
 Same as facePrint(u8 face, long decimal).
void facePrint (u8 face, unsigned int decimal)
 Print decimal as an unsigned decimal number, to the current xmit packet of face.
void facePrint (u8 face, long decimal)
 Print decimal as a signed decimal number, to the current xmit packet of face.
void facePrint (u8 face, unsigned long decimal)
 Same as facePrint(u8 face, unsigned long decimal, int code) with code set to DEC.
void facePrint (u8 face, unsigned long decimal, int code)
 Print num, in a format selected by code, to the current xmit packet of face.
void facePrint (u8 face, double val)
 Print val in a floating-point ASCII representation, with two digits to the right of the right of the decimal point.
void facePrintFace (u8 face)
 Print the 'face code' of face to the current xmit packet of face.
void facePrintln (u8 face)
 Terminate the current xmit packet on face.
void facePrintln (u8 face, const char *str)
 Same as facePrint(u8 face, const char * str) followed by facePrintln().
void facePrintln (u8 face, const u8 *str, u32 len)
 Same as facePrint(u8 face, const u8 * str,u32 len) followed by facePrintln().
void facePrintln (u8 face, int decimal)
 Same as facePrint(u8 face, int decimal) followed by facePrintln().
void facePrintln (u8 face, unsigned int decimal)
 Same as facePrint(u8 face, unsigned int decimal) followed by facePrintln().
void facePrintln (u8 face, long decimal)
 Same as facePrint(u8 face, long decimal) followed by facePrintln().
void facePrintln (u8 face, unsigned long decimal)
 Same as facePrint(u8 face, unsigned long decimal) followed by facePrintln().
void facePrintln (u8 face, unsigned long decimal, int code)
 Same as facePrint(u8 face, unsigned long decimal, int code) followed by facePrintln().
void facePrintln (u8 face, double val)
 Same as facePrint(u8 face, double val) followed by facePrintln().
void facePrintlnCheckByte (u8 face)
 Prints a 'packet check byte' and then terminates the packet via facePrintln(u8 face).
bool faceHasPrinter (u8 face)
bool faceFindFreeFace (u8 &foundFace)
void faceSetPrinter (u8 face, const FacePrinter *handler)
void faceUnsetPrinter (u8 face)
void print_startup_initialization ()

Detailed Description

Support for basic formatted printing.

Author:
David H. Ackley.
Date:
(C) 2009 All rights reserved.
Code License:
The GNU Lesser General Public License
License Note:
All code samples shown in documentation are placed into the public domain.

Function Documentation

void facePrint ( u8  face,
double  val 
)

Print val in a floating-point ASCII representation, with two digits to the right of the right of the decimal point.

Parameters:
face A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
val A double floating point value to be printed.
Side Effects:
The currently xmit packet of face increases in length as needed to print val, if packet length and buffer space room is available.
Example:
    ...
      int signedNum = -1;
      u32 unsignedNum = signedNum;
      facePrint(WEST,signedNum,DEC);               // Prints "-1": Signed num with code DEC
      facePrint(WEST,unsignedNum,DEC);             // Prints "4294967295": Unsigned num with code DEC
      facePrint(WEST,signedNum,HEX);               // Prints "FFFFFFFF": Non-DEC codes are always
      facePrint(WEST,unsignedNum,HEX);             // Prints "FFFFFFFF": printed as unsigned
    ...

void facePrint ( u8  face,
unsigned long  num,
int  code 
)

Print num, in a format selected by code, to the current xmit packet of face.

The possible format codes are:

  • DEC: Print one to ten bytes containing the base-10 representation of the 32 bits of num, using the ASCII characters '0' through '9'. See the 'd' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code DEC, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
  • HEX: Print one to eight bytes containing the base-16 representation of the 32 bits of num, using the ASCII characters '0' through '9' to represent 0 through 9, and 'A' through 'F' to represent 10 through 15. See the 'x' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code HEX, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
  • OCT: Print one to eleven bytes containing the base-8 representation of the 32 bits of num, using the ASCII characters '0' through '7' to represent 0 through 7. See the 'x' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code OCT, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
  • BIN: Print one to 32 bytes containing the base-2 representation of the 32 bits of num, using the ASCII characters '0' and '1' to represent 0 and 1. See the 'b' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code BIN, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
  • B36: Print one to six bytes containing the base-36 representation of the 32 bits of num, using the ASCII characters '0' through '9' to represent 0 through 9, and 'A' through 'Z' to represent 10 through 35. See the 't' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code B36, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
  • BELONG: Print exactly four bytes containing the 32 bits of num, with the four bytes in 'big endian order', also known as 'network order'. See the 'l' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code BELONG, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation. ]

BELONG is called a 'binary' code, but it must not be confused with BIN. With BELONG, each of the four output bytes may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

  • BESHORT: Print exactly two bytes containing the low-order 16 bits of num, with the two bytes in 'big endian order', also known as 'network order'. See the 'h' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code BESHORT, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.

BESHORT is called a 'binary' code, but it must not be confused with BIN. With BESHORT, each of the two output bytes may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

  • BYTE: Print exactly one byte containing the low-order 8 bits of num. See the 'c' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code BYTE, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.

BYTE is called a 'binary' code, but it must not be confused with BIN. With BYTE, the output byte may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

In addition to those codes, it is also possible to print in other bases between 2 and 36, if there is call to do so. For example, using a code value of 13 will select printing in base 13, using the ASCII characters '0' through '9' and 'A' through 'C'.

Parameters:
face A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
num A 32 bit number to be printed in a particular format.
code What format to use (see above).
Blinks:
E_API_FORMAT_ARG If code is an illegal code. The legal codes are BELONG, BESHORT or BYTE, or any value from 2 to 36 (which includes DEC, HEX, OCT, BIN, and B36).
Side Effects:
The currently xmit packet of face increases in length as needed by the selected format, if packet length and buffer space room is available.
Sample all-ASCII printable packet generation:
Example:
    void myHandler(u8 *) {
      facePrint(SOUTH,"L 1234 in:");
      facePrint(SOUTH," base 10="); facePrint(SOUTH, 1234, DEC); // Prints 1234
      facePrint(SOUTH," base 16="); facePrint(SOUTH, 1234, HEX); // Prints 4D2
      facePrint(SOUTH," base 8=");  facePrint(SOUTH, 1234, OCT); // Prints 2322
      facePrint(SOUTH," base 2=");  facePrint(SOUTH, 1234, BIN); // Prints 10011010010
      facePrint(SOUTH," base 36="); facePrint(SOUTH, 1234, B36); // Prints YA
      facePrintln(SOUTH);
    }

Sample binary packet generation:

Example:
    void setup() { /\* nothing to do *\/ }
    void loop() {                                  // Print a packet containing exactly eight bytes: 
      facePrint(ALL_FACES,"t");                    //  1 byte containing an ASCII 't'
      facePrint(ALL_FACES,millis(),BELONG);        // +4 bytes of board uptime in big endian
      facePrint(ALL_FACES,random(10000),BESHORT);  // +2 bytes of a random number 0..9999 in big endian
      facePrintln();                               // +1 byte containing an ASCII newline '\n'
      delay(1000);                                 // Wait a second, then do it again.
    }

void facePrint ( u8  face,
long  decimal 
)

Print decimal as a signed decimal number, to the current xmit packet of face.

Compare to facePrint(u8 face, unsigned long decimal). If decimal is less than zero, prints a '-' followed by the value of -decimal (note this gives the wrong output for the 'most negative' possible number.)

Parameters:
face A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
decimal A 32 bit number to be printed as a signed decimal value.
Side Effects:
The currently xmit packet of face gets up to eleven bytes longer, if packet length and buffer space room is available.
Example:
    void myHandler(u8 *) {
      long num = 123-456;               // Compute something. 'int' means 'signed 32 bit value'
      facePrint(EAST,"L answer=");     // Print some text to EastFace
      facePrintln(EAST,num);           // Prints '-333' and ends the packet
    }

void facePrint ( u8  face,
unsigned int  decimal 
)

Print decimal as an unsigned decimal number, to the current xmit packet of face.

Compare to facePrint(u8 face, int decimal).

Parameters:
face A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
decimal A 32 bit number to be printed as an unsigned decimal value.
Side Effects:
The currently xmit packet of face gets up to ten bytes longer, if packet length and buffer space room is available.
Example:
    void myHandler(u8 *) {
      u32 num = 123*456;             // Compute something. 'u32' means 'unsigned 32 bit value'
      facePrint(EAST,"L answer=");   // Print some text to EastFace
      facePrintln(EAST,num);         // Prints '56088' and ends the packet
    }

void facePrint ( u8  face,
const u8 *  str,
u32  len 
)

Print str, an array of bytes of length len, to the current xmit packet of face.

Compare to facePrint(u8 face, const char * str). If str is a packet, you may want to consider the '%p' or '%#p' formats of facePrintf() as well.

Parameters:
face A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
str A pointer to the byte array to append. Must be of length (at least) len; does not need to be null-terminated.
Blinks:
E_API_NULL_POINTER if str is null.
Side Effects:
The currently xmit packet of face gets up to len bytes longer, if packet length and buffer space room is available.
Example:
    void myHandler(u8 * packet) {
      facePrint(NORTH,"L I got a packet containing '");      // Print some text to NorthFace
      facePrint(NORTH,packet,packetLength(packet));          // Add entire contents of packet
      facePrintln(NORTH,"'");                                // Add an end quote then end the packet 
    }

void facePrint ( u8  face,
const char *  str 
)

Print the contents of a null-terminated string to the current xmit packet of face.

Compare to facePrint(u8 face, const u8 * str, u32 len).

Parameters:
face A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
str A pointer to the null-terminate string to append.
Blinks:
E_API_NULL_POINTER if str is null.
Side Effects:
The currently xmit packet of face gets up to strlen(str) bytes longer, if packet length and buffer space room is available.
Example:
    void myHandler(u8 * packet) {
      facePrint(NORTH,"L I received a packet of length "); // Print some text to NorthFace only
      facePrintln(NORTH,packetLength(packet), DEC);        // End packet after a decimal number
    }
Examples:
tee.cpp.

void facePrintFace ( u8  face  ) 

Print the 'face code' of face to the current xmit packet of face.

See also the 'F' format of facePrintf(u8 face, const char * format,...) for another way to perform this action, and in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with this method.

Parameters:
face A face code indicating which face(s) to print to. If face is NORTH, SOUTH, EAST, or WEST, then 'N', 'S', 'E', or 'W' is printed, respectively. If face is ALL_FACES, then for each eligible basic face, that face's own face code is printed to the corresponding face. If it is some other 'special' or 'virtual' face, then what is printed depends on the specific code involved.
Not so amazing sample:
Example:
    ...
      facePrintFace(NORTH);          // Prints 'N' to the NorthFace
      facePrintFace(WEST);           // Prints 'W' to the WestFace
    ...

Slightly more interesting sample:

Example:
    ...
      facePrint(ALL_FACES,"L You are my "); // These three lines print "L You are my N" to the NorthFace,
      facePrintFace(ALL_FACES);             // "L You are my S" to the SouthFace, "L You are my E" to the
      facePrintln(ALL_FACES);               // EastFace, and "L You are my W" to the WestFace (assuming
    ...                                     // they are all connected and processing packets).

void facePrintln ( u8  face,
double  val 
)

Same as facePrint(u8 face, double val) followed by facePrintln().

void facePrintln ( u8  face,
unsigned long  decimal,
int  code 
)

Same as facePrint(u8 face, unsigned long decimal, int code) followed by facePrintln().

void facePrintln ( u8  face,
unsigned long  decimal 
)

Same as facePrint(u8 face, unsigned long decimal) followed by facePrintln().

void facePrintln ( u8  face,
long  decimal 
)

Same as facePrint(u8 face, long decimal) followed by facePrintln().

void facePrintln ( u8  face,
unsigned int  decimal 
)

Same as facePrint(u8 face, unsigned int decimal) followed by facePrintln().

void facePrintln ( u8  face,
int  decimal 
)

Same as facePrint(u8 face, int decimal) followed by facePrintln().

void facePrintln ( u8  face,
const u8 *  str,
u32  len 
)

Same as facePrint(u8 face, const u8 * str,u32 len) followed by facePrintln().

void facePrintln ( u8  face,
const char *  str 
)

Same as facePrint(u8 face, const char * str) followed by facePrintln().

void facePrintln ( u8  face  ) 

Terminate the current xmit packet on face.

Normally the effect of this is to print an ASCII newline character, '
', but that behavior may be altered by the packet framing in use on the face.

Examples:
forward.cpp, pingpong.cpp, pingpong2.cpp, and tee.cpp.

void facePrintlnCheckByte ( u8  face  ) 

Prints a 'packet check byte' and then terminates the packet via facePrintln(u8 face).

A packet check byte is a single byte value that can optionally be placed as the last byte of a packet, to provide one measure of 'integrity check' that the packet data was not corrupted during transmission. The value of a packet check byte depends on on all the previous bytes in the packet, so if any bytes of the packet were garbled while in transit, it is fairly likely, though not guaranteed, that the check byte will fail to match so the error can be detected.

See the '%
' format of facePrintf(u8 face, const char * format,...) for another way to append a check byte to a packet, and see packetReadCheckByte(u8 * packet) or the '%
' format of packetScanf(u8 * packet, const char * format,...) for ways to read and verify a check byte that was appended to a packet.

Parameters:
face A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
Side Effects:
The currently xmit packet of face increases in length by one byte containing the computed check byte, if packet length and buffer space room is available.

void print ( double  val  ) 

Same as facePrint(u8 face, double val) with face set to ALL_FACES.

void print ( long  decimal,
int  code 
)

Same as facePrint(u8 face, unsigned long decimal, int code) with face set to ALL_FACES.

void print ( unsigned long  decimal  ) 

Same as facePrint(u8 face, unsigned long decimal) with face set to ALL_FACES.

void print ( long  decimal  ) 

Same as facePrint(u8 face, long decimal) with face set to ALL_FACES.

void print ( unsigned int  decimal  ) 

Same as facePrint(u8 face, unsigned long decimal) with face set to ALL_FACES.

void print ( int  decimal  ) 

Same as facePrint(u8 face, int decimal) with face set to ALL_FACES.

void print ( const u8 *  str,
u32  len 
)

Same as facePrint(u8 face, const u8 * str,u32 len) with face set to ALL_FACES.

void print ( const char *  str  ) 

Same as facePrint(u8 face, const char * str) with face set to ALL_FACES.

void printFace (  ) 

Same as facePrintFace(u8 face) with face set to ALL_FACES.

void println ( double  val  ) 

Same as facePrint(u8 face, double val) with face set to ALL_FACES.

void println ( long  decimal,
int  code 
)

Same as facePrintln(u8 face, unsigned long decimal, int code) with face set to ALL_FACES.

void println ( unsigned long  decimal  ) 

Same as facePrint(u8 face, unsigned long decimal) with face set to ALL_FACES.

void println ( long  decimal  ) 

Same as facePrintln(u8 face, long decimal) with face set to ALL_FACES.

void println ( unsigned int  decimal  ) 

Same as facePrintln(u8 face, unsigned long decimal) with face set to ALL_FACES.

void println ( int  decimal  ) 

Same as facePrintln(u8 face, int decimal) with face set to ALL_FACES.

void println ( const u8 *  str,
u32  len 
)

Same as facePrintln(u8 face, const u8 * str,u32 len) with face set to ALL_FACES.

void println ( const char *  str  ) 

Same as facePrintln(u8 face, const char * str) with face set to ALL_FACES.

void println (  ) 

Same as facePrintln(u8 face) with face set to ALL_FACES.

Examples:
alarm1.cpp, blinkySync.cpp, and pingpong2.cpp.

void printlnCheckByte (  ) 

Same as facePrintlnCheckByte() with face set to ALL_FACES.

Generated on Thu Sep 17 07:39:53 2009 for SFB by doxygen 1.5.9