Extended stream interface for terminal operations. More...

#include <Terminal.h>

Inheritance diagram for Terminal:

Public Types
enum	Mode { Serial, Telnet }
	Mode to operate in, Serial or Telnet. More...

enum	Color { Black = 0x00, DarkRed = 0x01, DarkGreen = 0x02, DarkYellow = 0x03, DarkBlue = 0x04, DarkMagenta = 0x05, DarkCyan = 0x06, LightGray = 0x07, DarkGray = 0x08, Red = 0x09, Green = 0x0A, Yellow = 0x0B, Blue = 0x0C, Magenta = 0x0D, Cyan = 0x0E, White = 0x0F }
	Terminal foreground or background colors. More...

Public Member Functions
	Terminal ()
	Constructs a terminal object. More...

virtual	~Terminal ()
	Destroys this terminal object.

void	begin (Stream &stream, Mode mode=Serial)
	Begins terminal operations on an underlying stream. More...

void	end ()
	Ends terminal operations on an underlying stream. More...

Stream *	stream () const
	Returns a pointer to the underlying Stream, or NULL if the stream has not been set with begin() yet. More...

Terminal::Mode	mode () const
	Returns the mode this terminal is operating in, Serial or Telnet. More...

virtual int	available ()
	Returns the number of bytes that are available for reading. More...

virtual int	peek ()
	Peeks at the next byte from the underlying stream. More...

virtual int	read ()
	Reads the next byte from the underlying stream. More...

virtual void	flush ()
	Flushes all data in the underlying stream.

virtual size_t	write (uint8_t c)
	Writes a single byte to the underlying stream. More...

virtual size_t	write (const uint8_t *buffer, size_t size)
	Writes a buffer of data to the underlying stream. More...

void	writeProgMem (const char *str)
	Writes a static string that is stored in program memory. More...

int	readKey ()
	Reads the next key that was typed on this terminal. More...

long	unicodeKey () const
	Gets the Unicode version of the last key returned by readKey(). More...

size_t	writeUnicode (long code)
	Writes a Unicode code point to the output in UTF-8 encoding. More...

int	columns () const
	Gets the number of columns in the window; defaults to 80. More...

int	rows () const
	Gets the number of rows in the window; defaults to 24. More...

bool	setWindowSize (int columns, int rows)
	Sets the number of columns and rows in the window. More...

void	clear ()
	Move the cursor to the top-left position and clear the screen.

void	clearToEOL ()
	Clears from the current cursor position to the end of the line.

void	cursorMove (int x, int y)
	Moves the cursor to a specific location in the window. More...

void	cursorLeft ()
	Moves the cursor left by one character. More...

void	cursorRight ()
	Moves the cursor right by one character. More...

void	cursorUp ()
	Moves the cursor up by one line. More...

void	cursorDown ()
	Moves the cursor down by one line. More...

void	backspace ()
	Backspaces over the last character. More...

void	insertLine ()
	Inserts a line at the cursor position. More...

void	insertChar ()
	Inserts a blank character at the cursor position. More...

void	deleteLine ()
	Deletes a line at the cursor position. More...

void	deleteChar ()
	Deletes the character at the cursor position. More...

void	scrollUp ()
	Scrolls the contents of the window up one line. More...

void	scrollDown ()
	Scrolls the contents of the window down one line. More...

void	normal ()
	Selects normal text with all attributes and colors off. More...

void	bold ()
	Enables bold text. More...

void	underline ()
	Enables underlined text.

void	blink ()
	Enables blinking text.

void	reverse ()
	Reverse the foreground and background colors for inverted text.

void	color (Color fg)
	Selects a text foreground color with the default background color. More...

void	color (Color fg, Color bg)
	Selects text foreground and background colors. More...

Static Public Member Functions
static bool	isWideCharacter (long code)
	Determine if a Unicode character is wide. More...

static size_t	utf8Length (long code)
	Determines the length of a Unicode code point in the UTF-8 encoding. More...

static size_t	utf8Format (uint8_t *buffer, long code)
	Formats a Unicode code point in a buffer in the UTF-8 encoding. More...

Detailed Description

Extended stream interface for terminal operations.

This class extends the standard Arduino Stream class with functions that are suitable for interfacing to VT100 terminal applications like PuTTY.

The following example initializes a terminal running on the primary Arduino serial port:

Terminal term;
void setup() {
    Serial.begin(9600);
    term.begin(Serial);
}

The readKey() function reads input from the underlying stream, decodes any VT100 key escape sequences that it finds, and reports them to the application using USB, ASCII, or Unicode key codes. This is typically used in the application's main loop as follows:

void loop() {
    int key = term.readKey();
    switch (key) {
    case -1:     break;      // No key available.
    case KEY_LEFT_ARROW:
        // Left arrow key has been pressed.
        ...
        break;
    case KEY_RIGHT_ARROW:
        // Right arrow key has been pressed.
        ...
        break;
    case KEY_ESC:
        // Escape key has been pressed.
        ...
        break;
    default:
        if (key >= 0x20 && key <= 7E) {
            // Visible ASCII character has been typed.
            ...
        }
        break;
    }
}

This class understands extended characters in the UTF-8 encoding, allowing the full Unicode character set to be used in applications. Extended Unicode characters are reported by readKey() with the key code KEY_UNICODE, with the actual code point returned via unicodeKey().

On the output side, UTF-8 strings can be written to the terminal using write(), or writeUnicode() can be used to write a single Unicode character in UTF-8.

Note: This class does not have any special support for right-to-left scripts or composed characters. Unicode characters are read and written in the order in which they arrive. Applications may need to alter strings to display them correctly in such scripts. Patches are welcome to fix this.

See Also: Shell

Definition at line 36 of file Terminal.h.

Member Enumeration Documentation

enum Terminal::Color

Terminal foreground or background colors.

Enumerator
Black	Color is black.
DarkRed	Color is dark red.
DarkGreen	Color is dark green.
DarkYellow	Color is dark yellow.
DarkBlue	Color is dark blue.
DarkMagenta	Color is dark magenta.
DarkCyan	Color is dark cyan.
LightGray	Color is light gray.
DarkGray	Color is dark gray.
Red	Color is light red.
Green	Color is light green.
Yellow	Color is light yellow.
Blue	Color is light blue.
Magenta	Color is light magenta.
Cyan	Color is light cyan.
White	Color is white.

Definition at line 102 of file Terminal.h.

enum Terminal::Mode

Mode to operate in, Serial or Telnet.

Enumerator
Serial	Operates the terminal in serial mode.
Telnet	Operates the terminal in telnet mode.

Definition at line 42 of file Terminal.h.

Constructor & Destructor Documentation

Terminal::Terminal ( )

Constructs a terminal object.

This constructor must be followed by a call to begin() to specify the underlying stream to use for reading and writing.

See Also: begin()

Definition at line 133 of file Terminal.cpp.

Member Function Documentation

int Terminal::available ( )

virtual

Returns the number of bytes that are available for reading.

Note: It is possible for this function to return a positive value while readKey() does not produce a new key. This can happen with VT100 key escape sequences and UTF-8 characters that extend over multiple bytes.

See Also: readKey()

Definition at line 228 of file Terminal.cpp.

void Terminal::backspace ( )

Backspaces over the last character.

This function prints CTRL-H, a space, and another CTRL-H to backspace over and erase the last character on the current line.

If the last character was a wide Unicode character, then two calls to this function are required to erase it. See isWideCharacter() for more information.

See Also: isWideCharacter()

Definition at line 949 of file Terminal.cpp.

void Terminal::begin	(	Stream &	stream,
		Mode	mode = `Serial`
	)

Begins terminal operations on an underlying stream.

Parameters

stream	The underlying stream, whether a serial port, TCP connection, or some other stream.
mode	The mode to operate in, either Serial or Telnet.

If Telnet mode is selected, then embedded commands and options from the telnet protocol (RFC 854) will be interpreted. This is useful if the underlying stream is a TCP connection on port 23. The mode operates as a telnet server.

See Also: end(), stream(), mode()

Definition at line 183 of file Terminal.cpp.

void Terminal::bold ( )

Enables bold text.

See Also: normal()

Definition at line 1037 of file Terminal.cpp.

void Terminal::color ( Color fg )

Selects a text foreground color with the default background color.

Parameters

fg	The foreground color to select.

All other text attributes (reverse, underline, etc) are disabled.

The following example displays a warning string with the initial word in red and all following words in normal text:

term.color(Terminal::Red);
term.print("WARNING: ");
term.normal();
term.println("All files on the SD card will be deleted!");

See Also: normal()

Definition at line 1174 of file Terminal.cpp.

void Terminal::color	(	Color	fg,
		Color	bg
	)

Selects text foreground and background colors.

Parameters

fg	The foreground color to select.
bg	The background color to select.

All other text attributes (reverse, underline, etc) are disabled.

See Also: normal()

Definition at line 1206 of file Terminal.cpp.

int Terminal::columns ( ) const

inline

Gets the number of columns in the window; defaults to 80.

See Also: rows(), setWindowSize(), cursorMove()

Definition at line 72 of file Terminal.h.

void Terminal::cursorDown ( )

Moves the cursor down by one line.

See Also: cursorUp(), cursorLeft(), cursorRight(), cursorMove()

Definition at line 931 of file Terminal.cpp.

void Terminal::cursorLeft ( )

Moves the cursor left by one character.

See Also: cursorRight(), cursorUp(), cursorDown(), cursorMove()

Definition at line 898 of file Terminal.cpp.

void Terminal::cursorMove	(	int	x,
		int	y
	)

Moves the cursor to a specific location in the window.

Parameters

x	The x position for the cursor between 0 and columns() - 1.
y	The y position for the cursor between 0 and rows() - 1.

See Also: cursorLeft(), columns(), rows(), setWindowSize()

Definition at line 866 of file Terminal.cpp.

void Terminal::cursorRight ( )

Moves the cursor right by one character.

See Also: cursorLeft(), cursorUp(), cursorDown(), cursorMove()

Definition at line 909 of file Terminal.cpp.

void Terminal::cursorUp ( )

Moves the cursor up by one line.

See Also: cursorDown(), cursorLeft(), cursorRight(), cursorMove()

Definition at line 920 of file Terminal.cpp.

void Terminal::deleteChar ( )

Deletes the character at the cursor position.

See Also: deleteLine(), insertChar()

Definition at line 993 of file Terminal.cpp.

void Terminal::deleteLine ( )

Deletes a line at the cursor position.

See Also: deleteChar(), insertLine()

Definition at line 982 of file Terminal.cpp.

void Terminal::end ( )

Ends terminal operations on an underlying stream.

This function may be useful if you want to detach the terminal from the underlying stream so that it can be used for something else.

Definition at line 198 of file Terminal.cpp.

void Terminal::insertChar ( )

Inserts a blank character at the cursor position.

See Also: insertLine(), deleteChar()

Definition at line 971 of file Terminal.cpp.

void Terminal::insertLine ( )

Inserts a line at the cursor position.

See Also: insertChar(), deleteLine()

Definition at line 960 of file Terminal.cpp.

bool Terminal::isWideCharacter ( long code )

static

Determine if a Unicode character is wide.

Parameters

code	The code point for the Unicode character.

Returns: Returns true if code is a wide character, false otherwise.

Wide characters typically come from East Asian languages and occupy two spaces in a terminal. Two calls to backspace() are required to erase such characters.

References: http://www.unicode.org/reports/tr11/, http://www.unicode.org/Public/UCD/latest/ucd/EastAsianWidth.txt

See Also: backspace(), writeUnicode()

Definition at line 1247 of file Terminal.cpp.

Terminal::Mode Terminal::mode ( ) const

inline

Returns the mode this terminal is operating in, Serial or Telnet.

See Also: begin()

Definition at line 52 of file Terminal.h.

void Terminal::normal ( )

Selects normal text with all attributes and colors off.

See Also: color(), bold(), underline(), blink(), reverse()

Definition at line 1026 of file Terminal.cpp.

int Terminal::peek ( )

virtual

Peeks at the next byte from the underlying stream.

Returns: The next byte or -1 if no bytes are available yet.

See Also: read()

Definition at line 240 of file Terminal.cpp.

int Terminal::read ( )

virtual

Reads the next byte from the underlying stream.

Returns: Returns 0x00 to 0xFF if a byte is ready, or -1 if none available.

This function performs a low-level read on the underlying byte stream without applying any specific interpretation to the byte. In particular, escape sequences corresponding to arrow and function keys will not be recognized.

Applications will usually want to call readKey() instead to handle escape sequences for arrow and function keys. This function is provided as a convenience to implement the parent Stream interface.

See Also: readKey()

Definition at line 261 of file Terminal.cpp.

int Terminal::readKey ( )

Reads the next key that was typed on this terminal.

Returns: Returns -1 if there is no key ready yet; 0x00 to 0x7F for an ASCII character; KEY_UNICODE for an extended Unicode code point, or a USB keyboard code for special arrow or function keys.

For example, if the user types the Home key, then this function will return KEY_HOME. If the user types the capital letter A, then this function will return 0x41.

If the user types an extended Unicode character (U+0080 and higher), then this function will return KEY_UNICODE. The application should call unicodeKey() to retrieve the actual code point. All Unicode characters are assumed to be in the UTF-8 encoding on the stream.

Some ASCII control characters correspond to special keys and will be mapped appropriately:

0x08 (CTRL-H) and 0x7F (DEL) are mapped to KEY_BACKSPACE
0x0D (CTRL-M) and 0x0A (CTRL-J) are mapped to KEY_RETURN
0x09 (CTRL-I) is mapped to KEY_TAB
0x1B (CTRL-[) is mapped to KEY_ESCAPE

In all of these cases, the original ASCII code will be reported by unicodeKey(). As a special case, if 0x0D is immediately followed by 0x0A (that is, CRLF) then KEY_RETURN will be reported only once with unicodeKey() set to 0x0D. This ensures that all line ending types are mapped to a single KEY_RETURN report.

If the window size has changed due to a remote event, then KEY_WINSIZE will be returned. This can allow the caller to clear and redraw the window in the new size.

See Also: unicodeKey(), read()

Definition at line 387 of file Terminal.cpp.

int Terminal::rows ( ) const

inline

Gets the number of rows in the window; defaults to 24.

See Also: columns(), setWindowSize(), cursorMove()

Definition at line 73 of file Terminal.h.

void Terminal::scrollDown ( )

Scrolls the contents of the window down one line.

See Also: scrollUp()

Definition at line 1015 of file Terminal.cpp.

void Terminal::scrollUp ( )

Scrolls the contents of the window up one line.

See Also: scrollDown()

Definition at line 1004 of file Terminal.cpp.

bool Terminal::setWindowSize	(	int	columns,
		int	rows
	)

Sets the number of columns and rows in the window.

Parameters

columns	The number of columns between 1 and 10000.
rows	The number of rows between 1 and 10000.

Returns: Returns true if the window size has changed.

This function should be used if the application has some information about the actual window size. For serial ports, this usually isn't available but telnet and ssh sessions can get the window size from the remote host.

The window size defaults to 80x24 which is the standard default for terminal programs like PuTTY that emulate a VT100.

If the window size changes due to a remote event, readKey() will return KEY_WINSIZE to inform the application.

See Also: columns(), rows(), readKey()

Definition at line 801 of file Terminal.cpp.

Stream * Terminal::stream ( ) const

inline

Returns a pointer to the underlying Stream, or NULL if the stream has not been set with begin() yet.

See Also: begin()

Definition at line 51 of file Terminal.h.

long Terminal::unicodeKey ( ) const

inline

Gets the Unicode version of the last key returned by readKey().

If readKey() returned an ASCII character (0x00 to 0x7F) or KEY_UNICODE, then this function can be used to query the full Unicode code point for the key that was typed. If some other key is typed, or no key was typed, then this function will return -1.

Unicode code points range between 0 and 0x10FFFF.

See Also: readKey(), writeUnicode()

Definition at line 68 of file Terminal.h.

size_t Terminal::utf8Format	(	uint8_t *	buffer,
		long	code
	)

static

Formats a Unicode code point in a buffer in the UTF-8 encoding.

Parameters

buffer	The buffer to write the UTF-8 encoding to. At most 4 bytes will be written to this buffer.
code	The code point to be written between 0 and 0x10FFFF.

Returns: The number of bytes that were written to buffer to represent code. Returns zero if code is not a valid code point.

See Also: utf8Length(), writeUnicode()

Definition at line 1334 of file Terminal.cpp.

size_t Terminal::utf8Length ( long code )

static

Determines the length of a Unicode code point in the UTF-8 encoding.

Parameters

code	The code point to be written between 0 and 0x10FFFF.

Returns: The number of bytes that makes up the UTF-8 encoding of code. Returns zero if code is not a valid code point.

See Also: utf8Format(), writeUnicode()

Definition at line 1302 of file Terminal.cpp.

size_t Terminal::write ( uint8_t c )

virtual

Writes a single byte to the underlying stream.

Parameters

c	The byte to write.

Returns: The number of bytes written, zero on error.

Definition at line 286 of file Terminal.cpp.

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

virtual

Writes a buffer of data to the underlying stream.

Parameters

buffer	Points to the buffer to write.
size	The number of bytes in the buffer.

Returns: The number of bytes written, which may be short on error.

Definition at line 299 of file Terminal.cpp.

void Terminal::writeProgMem ( const char * str )

Writes a static string that is stored in program memory.

Parameters

str	Points to the NUL-terminated string in program memory.

This is a convenience function for printing static strings that are stored in program memory.

See Also: write()

Definition at line 314 of file Terminal.cpp.

size_t Terminal::writeUnicode ( long code )

Writes a Unicode code point to the output in UTF-8 encoding.

Parameters

code	The code point to be written between 0 and 0x10FFFF.

Returns: The number of bytes that were written to the underlying stream to represent code. Returns zero if code is not a valid code point.

This function is useful when a specific Unicode character is desired; for example the code point 0x2264 corresponds to the less than or equal to operator "≤". See the Unicode standard for more information.

Unicode characters between 0x00 and 0x7F and strings that are already in the UTF-8 encoding can also be written using write().

See Also: write()

Definition at line 757 of file Terminal.cpp.

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

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation