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 ()
 Gets the number of codes available in the keyboard queue. More...
 
int availableForWrite ()
 Determines number of codes that the display input queue can still accept. More...
 
void begin ()
 Initializes the terminal. More...
 
void clear ()
 Clears the screen. More...
 
void connectLocally ()
 Permits using of terminal locally. More...
 
void connectSerialPort (HardwareSerial &serialPort, bool autoXONXOFF=true)
 Connects a remove host using the specified serial port. More...
 
void enableCursor (bool value)
 Enables or disables cursor. More...
 
void end ()
 Finalizes the terminal. More...
 
void flush (bool waitVSync)
 Waits for all codes sent to the display has been processed. More...
 
void flush ()
 Waits for all codes sent to the display has been processed. More...
 
int getColumns ()
 Returns the number of columns. More...
 
int getRows ()
 Returns the number of lines. More...
 
void loadFont (FontInfo const *font)
 Sets the font to use. More...
 
void localWrite (uint8_t c)
 Injects keys into the keyboard queue. More...
 
void localWrite (char const *str)
 Injects a string of keys into the keyboard queue. More...
 
int peek ()
 Reads a code from the keyboard without advancing to the next one. More...
 
void pollSerialPort ()
 Pools the serial port for incoming data. More...
 
int read ()
 Reads codes from keyboard. More...
 
void setBackgroundColor (Color color, bool setAsDefault=true)
 Sets the background color. More...
 
void setForegroundColor (Color color, bool setAsDefault=true)
 Sets the foreground color. More...
 
void setLogStream (Stream &stream)
 Sets the stream where to output debugging logs. More...
 
void setTerminalType (TermInfo const *value)
 Sets the terminal type to emulate specifying conversion tables. More...
 
void setTerminalType (TermType value)
 Sets the terminal type to emulate. More...
 
TermInfo const & terminalType ()
 Determines current terminal type. More...
 
int write (const uint8_t *buffer, int size)
 Sends specified number of codes to the display. More...
 
size_t write (uint8_t c)
 Sends 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.

Example 1:

TerminalClass Terminal;

// 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:

TerminalClass Terminal;

// 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 ( )

Gets 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.

◆ availableForWrite()

int fabgl::TerminalClass::availableForWrite ( )

Determines 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 ( )

Initializes the terminal.

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

◆ clear()

void fabgl::TerminalClass::clear ( )

Clears 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();

◆ 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.

◆ connectSerialPort()

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

Connects 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);

◆ enableCursor()

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

Enables or disables cursor.

Parameters
valueIf true the cursor becomes visible.

◆ end()

void fabgl::TerminalClass::end ( )

Finalizes the terminal.

Applications should call this method before screen resolution changes.

◆ flush() [1/2]

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

Waits 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 ( )

Waits 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

Returns the number of columns.

Returns
The number of columns (in characters).

◆ getRows()

int fabgl::TerminalClass::getRows ( )
inline

Returns the number of lines.

Returns
The number of lines (in characters).

◆ loadFont()

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

Sets 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)

Injects 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)

Injects 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 ( )

Reads 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 ( )

Pools 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();
  }

◆ read()

int fabgl::TerminalClass::read ( )

Reads 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).

◆ setBackgroundColor()

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

Sets 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);

◆ setForegroundColor()

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

Sets 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);

◆ setLogStream()

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

Sets 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);

◆ setTerminalType() [1/2]

void fabgl::TerminalClass::setTerminalType ( TermInfo const *  value)

Sets the terminal type to emulate specifying conversion tables.

Parameters
valueConversione tables for the terminal to emulate. nullptr = native ANSI/VT terminal.

Default and native is ANSI/VT100 mode. Other terminals are emulated translating to native mode.

◆ setTerminalType() [2/2]

void fabgl::TerminalClass::setTerminalType ( TermType  value)

Sets the terminal type to emulate.

Parameters
valueA terminal to emulate

Default and native is ANSI/VT100 mode. Other terminals are emulated translating to native mode.

◆ terminalType()

TermInfo const& fabgl::TerminalClass::terminalType ( )
inline

Determines current terminal type.

Returns
Terminal type

◆ write() [1/2]

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

Sends 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");

◆ write() [2/2]

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

Sends 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: