FabGL
ESP32 VGA Controller and Graphics Library
fabgl::TerminalClass Class Reference

An ANSI-VT100 compatible display terminal. More...

#include <terminal.h>

Inherits Stream.

Public Member Functions

int available ()
 Get the number of codes available in the keyboard queue. More...
 
int availableForWrite ()
 Return number of codes that the display input queue can still accept. More...
 
void begin ()
 Initialize the terminal. More...
 
void clear ()
 Clear the screen. More...
 
void connectLocally ()
 Permits using of terminal locally. More...
 
void connectSerialPort (HardwareSerial &serialPort, bool autoXONXOFF=true)
 Connect a remove host using the specified serial port. More...
 
void enableCursor (bool value)
 Enable or disable cursor. More...
 
void end ()
 Finalize the terminal. More...
 
void flush (bool waitVSync)
 Wait for all codes sent to the display has been processed. More...
 
void flush ()
 Wait for all codes sent to the display has been processed. More...
 
int getColumns ()
 Return the number of columns. More...
 
int getRows ()
 Return the number of lines. More...
 
void loadFont (FontInfo const *font)
 Set the font to use. More...
 
void localWrite (uint8_t c)
 Inject keys into the keyboard queue. More...
 
void localWrite (char const *str)
 Inject a string of keys into the keyboard queue. More...
 
int peek ()
 Read a code from the keyboard without advancing to the next one. More...
 
void pollSerialPort ()
 Pool the serial port for incoming data. More...
 
int read ()
 Read codes from keyboard. More...
 
void setBackgroundColor (Color color, bool setAsDefault=true)
 Set the background color. More...
 
void setForegroundColor (Color color, bool setAsDefault=true)
 Set the foreground color. More...
 
void setLogStream (Stream &stream)
 Set the stream where to output debugging logs. More...
 
int write (const uint8_t *buffer, int size)
 Send specified number of codes to the display. More...
 
size_t write (uint8_t c)
 Send a single code to the display. More...
 

Detailed Description

An ANSI-VT100 compatible display terminal.

Implements most of common ANSI, VT52, VT100, VT200, VT300, VT420 and VT500 escape codes, like non-CSI codes (RIS, IND, DECID, DECDHL, etc..),
like CSI codes (private modes, CUP, TBC, etc..), like CSI-SGR codes (bold, italic, blinking, etc...) and like DCS codes (DECRQSS, etc..).
Supports convertion from PS/2 keyboard virtual keys to ANSI or VT codes (keypad, cursor keys, function keys, etc..).

TerminalClass can receive codes to display from Serial Port or it can be controlled directly from the application. In the same way TerminalClass can send keyboard codes to a Serial Port or directly to the application.

For default it supports 80x25 or 132x25 characters at 640x350. However any custom resolution and text buffer size is supported specifying a custom font.

There are three cursors styles (block, underlined and bar), blinking or not blinking.

TerminalClass inherits from Stream so applications can use all Stream and Print input and output methods.

TerminalClass passes 95/110 of VTTEST VT100/VT102 Compatibility Test Score Sheet.

Applications do not need to create an instance of TerminalClass because an instance named Terminal is created automatically.

Example 1:

// Setup 80x25 columns loop-back terminal (send what you type on keyboard to the display)
void setup() {
  Keyboard.begin(GPIO_NUM_33, GPIO_NUM_32);  // GPIOs for keyboard (CLK, DATA)

  // GPIOs for VGA (RED0, RED1, GREEN0, GREEN1, BLUE0, BLUE1, HSYNC, VSYNC)
  VGAController.begin(GPIO_NUM_22, GPIO_NUM_21, GPIO_NUM_19, GPIO_NUM_18, GPIO_NUM_5, GPIO_NUM_4, GPIO_NUM_23, GPIO_NUM_15);
  VGAController.setResolution(VGA_640x350_70HzAlt1, 640, 350); // 640x350, 80x25 columns

  Terminal.begin();
  Terminal.connectLocally();      // to use Terminal.read(), available(), etc..
  Terminal.enableCursor(true);
}

void loop() {
  if (Terminal.available()) {
    char c = Terminal.read();
    switch (c) {
      case 0x7F:       // DEL -> backspace + ESC[K
        Terminal.write("\b\e[K");
        break;
      case 0x0D:       // CR  -> CR + LF
        Terminal.write("\r\n");
        break;
      case 32 ... 126: // printable chars
        Terminal.write(c);
        break;
    }
  }
}

Example 2:

// Setup 80x25 columns terminal using UART2 to communicate with the server,
// VGA to display output and PS2 device as keyboard input
void setup() {
  Serial2.begin(115200);

  Keyboard.begin(GPIO_NUM_33, GPIO_NUM_32); // GPIOs for keyboard (CLK, DATA)

  // GPIOs for VGA (RED0, RED1, GREEN0, GREEN1, BLUE0, BLUE1, HSYNC, VSYNC)
  VGAController.begin(GPIO_NUM_22, GPIO_NUM_21, GPIO_NUM_19, GPIO_NUM_18, GPIO_NUM_5, GPIO_NUM_4, GPIO_NUM_23, GPIO_NUM_15);
  VGAController.setResolution(VGA_640x350_70HzAlt1, 640, 350); // 640x350, 80x25 columns

  Terminal.begin();
  Terminal.connectSerialPort(Serial2);
  Terminal.enableCursor(true);
}

void loop() {
  Terminal.pollSerialPort();
}

Member Function Documentation

◆ available()

int fabgl::TerminalClass::available ( )

Get the number of codes available in the keyboard queue.

Keyboard queue is available only after TerminalClass.connectLocally() call.

Returns
The number of codes available to read.
Examples:
LoopbackTerminal/LoopbackTerminal.ino, and NetworkTerminal/NetworkTerminal.ino.

◆ availableForWrite()

int fabgl::TerminalClass::availableForWrite ( )

Return number of codes that the display input queue can still accept.

Returns
The size (in characters) of remaining space in the display queue.

◆ begin()

void fabgl::TerminalClass::begin ( )

Initialize the terminal.

Applications should call this method before any other method call or after resolution has been set.

Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ clear()

void fabgl::TerminalClass::clear ( )

Clear the screen.

Clears the screen sending "CSI 2 J" command to the screen.

Example:

   // Fill the screen with blue
   Terminal.setBackgroundColor(Color::Blue);
   Terminal.clear();
Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, and NetworkTerminal/NetworkTerminal.ino.

◆ connectLocally()

void fabgl::TerminalClass::connectLocally ( )

Permits using of terminal locally.

Create a queue where to put ANSI keys decoded from keyboard or as replies to terminal queries.
This queue is accessible with read(), available() and peek() methods.

Example:

   Terminal.begin();
   Terminal.connectLocally();
   // from here you can use Terminal.read() to receive keys from keyboard
   // and Terminal.write() to control the display.
Examples:
LoopbackTerminal/LoopbackTerminal.ino, and NetworkTerminal/NetworkTerminal.ino.

◆ connectSerialPort()

void fabgl::TerminalClass::connectSerialPort ( HardwareSerial &  serialPort,
bool  autoXONXOFF = true 
)

Connect a remove host using the specified serial port.

When serial port is set, the typed keys on PS/2 keyboard are encoded as ANSI/VT100 codes and then sent to the specified serial port.
Also replies to terminal queries like terminal identification, cursor position, etc.. will be sent to the serial port.
Call TerminalClass.pollSerialPort() to send codes from serial port to the display.

Parameters
serialPortThe serial port to use.
autoXONXOFFIf true uses software flow control (XON/XOFF).

Example:

  Terminal.begin();
  Terminal.connectSerialPort(Serial);
Examples:
AnsiTerminal/AnsiTerminal.ino.

◆ enableCursor()

void fabgl::TerminalClass::enableCursor ( bool  value)

Enable or disable cursor.

Parameters
valueIf true the cursor becomes visible.
Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ end()

void fabgl::TerminalClass::end ( )

Finalize the terminal.

Applications should call this method before screen resolution changes.

◆ flush() [1/2]

void fabgl::TerminalClass::flush ( bool  waitVSync)

Wait for all codes sent to the display has been processed.

Parameters
waitVSyncIf true codes are processed during screen retrace time (starting from VSync up to about first top visible row). When false all messages are processed immediately.

◆ flush() [2/2]

void fabgl::TerminalClass::flush ( )

Wait for all codes sent to the display has been processed.

Codes are processed during screen retrace time (starting from VSync up to about first top visible row).

◆ getColumns()

int fabgl::TerminalClass::getColumns ( )
inline

Return the number of columns.

Returns
The number of columns (in characters).
Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ getRows()

int fabgl::TerminalClass::getRows ( )
inline

Return the number of lines.

Returns
The number of lines (in characters).
Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ loadFont()

void fabgl::TerminalClass::loadFont ( FontInfo const *  font)

Set the font to use.

Terminal automatically choises the best font considering screen resolution and required number of columns and rows.
Particular cases require setting custom fonts, so applications can use TerminalClass.loadFont().

Parameters
fontSpecifies font info for the font to set.

◆ localWrite() [1/2]

void fabgl::TerminalClass::localWrite ( uint8_t  c)

Inject keys into the keyboard queue.

Characters added with localWrite() will be received with read(), available() and peek() methods.

Parameters
cASCII code to inject into the queue.

◆ localWrite() [2/2]

void fabgl::TerminalClass::localWrite ( char const *  str)

Inject a string of keys into the keyboard queue.

Characters added with localWrite() will be received with read(), available() and peek() methods.

Parameters
strA string of ASCII codes to inject into the queue.

◆ peek()

int fabgl::TerminalClass::peek ( )

Read a code from the keyboard without advancing to the next one.

Keyboard queue is available only after TerminalClass.connectLocally() call.

Returns
The next code, or -1 if none is available.

◆ pollSerialPort()

void fabgl::TerminalClass::pollSerialPort ( )

Pool the serial port for incoming data.

Tnis method needs to be called in the application main loop to check if new data is coming from the current serial port (specified using TerminalClass.connectSerialPort).

Example:

  void loop()
  {
    Terminal.pollSerialPort();
  }
Examples:
AnsiTerminal/AnsiTerminal.ino.

◆ read()

int fabgl::TerminalClass::read ( )

Read codes from keyboard.

Keyboard queue is available only after TerminalClass.connectLocally() call.

Returns
The first code of incoming data available (or -1 if no data is available).
Examples:
LoopbackTerminal/LoopbackTerminal.ino, and NetworkTerminal/NetworkTerminal.ino.

◆ setBackgroundColor()

void fabgl::TerminalClass::setBackgroundColor ( Color  color,
bool  setAsDefault = true 
)

Set the background color.

Sets the background color sending an SGR ANSI code and optionally the default background color (used resetting the terminal).

Parameters
colorCurrent or default background color.
setAsDefaultIf true the specified color is also used as default.

Example:

   Terminal.setBackgroundColor(Color::Black);
Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, and NetworkTerminal/NetworkTerminal.ino.

◆ setForegroundColor()

void fabgl::TerminalClass::setForegroundColor ( Color  color,
bool  setAsDefault = true 
)

Set the foreground color.

Sets the foreground color sending an SGR ANSI code and optionally the default foreground color (used resetting the terminal).

Parameters
colorCurrent or default foreground color.
setAsDefaultIf true the specified color is also used as default.

Example:

   Terminal.setForegroundColor(Color::White);
Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, and NetworkTerminal/NetworkTerminal.ino.

◆ setLogStream()

void fabgl::TerminalClass::setLogStream ( Stream &  stream)
inline

Set the stream where to output debugging logs.

Logging info sents to the logging stream are detailed by FABGLIB_TERMINAL_DEBUG_REPORT_.... macros in fabglconf.h configuration file.

Parameters
streamThe logging stream.

Example:

   Serial.begin(115200);
   Terminal.begin();
   Terminal.setLogStream(Serial);
Examples:
NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ write() [1/2]

int fabgl::TerminalClass::write ( const uint8_t *  buffer,
int  size 
)

Send specified number of codes to the display.

Codes can be ANSI/VT codes or ASCII characters.

Parameters
bufferPointer to codes buffer.
sizeNumber of codes in the buffer.
Returns
The number of codes written.

Example:

   // Clear the screen and print "Hello World!"
   Terminal.write("\e[2J", 4);
   Terminal.write("Hellow World!\r\n", 15);

   // The same without size specified
   Terminal.write("\e[2J");
   Terminal.write("Hellow World!\r\n");
Examples:
AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ write() [2/2]

size_t fabgl::TerminalClass::write ( uint8_t  c)

Send a single code to the display.

Code can be only of the ANSI/VT codes or ASCII characters.

Parameters
cThe code to send.
Returns
The number of codes written.

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