FabGL
ESP32 VGA Controller and Graphics Library
|
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... | |
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(); }
int fabgl::TerminalClass::available | ( | ) |
Gets the number of codes available in the keyboard queue.
Keyboard queue is available only after TerminalClass.connectLocally() call.
int fabgl::TerminalClass::availableForWrite | ( | ) |
Determines number of codes that the display input queue can still accept.
void fabgl::TerminalClass::begin | ( | ) |
Initializes the terminal.
Applications should call this method before any other method call or after resolution has been set.
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();
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.
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.
serialPort | The serial port to use. |
autoXONXOFF | If true uses software flow control (XON/XOFF). |
Example:
Terminal.begin(); Terminal.connectSerialPort(Serial);
void fabgl::TerminalClass::enableCursor | ( | bool | value | ) |
Enables or disables cursor.
value | If true the cursor becomes visible. |
void fabgl::TerminalClass::end | ( | ) |
Finalizes the terminal.
Applications should call this method before screen resolution changes.
void fabgl::TerminalClass::flush | ( | bool | waitVSync | ) |
Waits for all codes sent to the display has been processed.
waitVSync | If 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. |
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).
|
inline |
Returns the number of columns.
|
inline |
Returns the number of lines.
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().
font | Specifies font info for the font to set. |
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.
c | ASCII code to inject into the queue. |
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.
str | A string of ASCII codes to inject into the queue. |
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.
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(); }
int fabgl::TerminalClass::read | ( | ) |
Reads codes from keyboard.
Keyboard queue is available only after TerminalClass.connectLocally() call.
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).
color | Current or default background color. |
setAsDefault | If true the specified color is also used as default. |
Example:
Terminal.setBackgroundColor(Color::Black);
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).
color | Current or default foreground color. |
setAsDefault | If true the specified color is also used as default. |
Example:
Terminal.setForegroundColor(Color::White);
|
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.
stream | The logging stream. |
Example:
Serial.begin(115200); Terminal.begin(); Terminal.setLogStream(Serial);
void fabgl::TerminalClass::setTerminalType | ( | TermInfo const * | value | ) |
Sets the terminal type to emulate specifying conversion tables.
value | Conversione 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.
void fabgl::TerminalClass::setTerminalType | ( | TermType | value | ) |
Sets the terminal type to emulate.
value | A terminal to emulate |
Default and native is ANSI/VT100 mode. Other terminals are emulated translating to native mode.
|
inline |
Determines current terminal type.
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.
buffer | Pointer to codes buffer. |
size | Number of codes in the buffer. |
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");
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.
c | The code to send. |