VT-AC

  ___ ___ _______        _______ _______ 
 |   Y   |       |______|   _   |   _   |
 |.  |   |.|   | |______|.  1   |.  1___|
 |.  |   `-|.  |-'      |.  _   |.  |___ 
 |:  1   | |:  |        |:  |   |:  1   |
  \:.. ./  |::.|        |::.|:. |::.. . |
   `---'   `---'        `--- ---`-------'

A fantasy ASCII terminal emulator.

Features

• Emulates a simple ASCII terminal with 40 columns and 30 rows or 8x8 pixel blocks.
• Controllable via serial port using only standard ASCII data.
• 320 x 240 native pixel display area.
• Uses a classic 8x8 pixel font (IBM PC BIOS / Code Page 437) for character rendering.
• Text or graphics mode support.
• 256 colors available (RGB332).
• Set foreground and background colors for each 8x8 pixel block or 8x1 pixel row.
• Connects via serial port for real-time data communication with Arduino, Raspberry Pi, 6502 computer, or anything with a serial port!
• Or you can load binary data files directly into the terminal to be parsed and displayed.
• Supports configurable baud rate, parity, data bits, and stop bits.
• Fullscreen mode for immersive terminal experience.
• Adjustable scaling for better visibility.

Quick Start

1. Install VT-AC globally via NPM:

npm install -g vtac-terminal

2. Connect a serial device (e.g., Arduino) to your computer.
3. Open VT-AC terminal emulator with the appropriate path to the serial port:

vtac -p /dev/ttyUSB0

4. Start sending ASCII data from your serial device to see it displayed in the VT-AC terminal!

Character Set

Palette

Instruction Set

The VT-AC terminal supports a simple instruction set using standard ASCII values to control its behavior. Below is a summary of the supported instructions:

Instruction	# of Bytes	Command	Description
0x00	1	NULL	No operation
0x01	1	HOME	Move cursor to home position (0,0)
0x02	2	Cursor Character	2nd byte is character to use, or $00 to turn off (Default=$00)
0x03	1	Cursor Mode	Toggle cursor mode between solid/blinking (Default=solid)
0x04	1	Reset	Reset terminal (text mode, clear screen, cursor home-off-solid, bg=$00, fg=$FF)
0x05	1	N/A	Reserved for future use
0x06	1	N/A	Reserved for future use
0x07	1	BELL	Play bell sound
0x08	1	BS	Backspace
0x09	1	TAB	Move cursor to next tab stop
0x0A	1	LF	Line feed (move cursor down, same column)
0x0B	1	Screen Mode	Toggle screen mode between text/graphics modes (Default=text)
0x0C	1	Clear Screen	Clear the screen
0x0D	1	CR	Carriage return (move cursor to start of line)
0x0E	2	Set Column	2nd byte is column 0 ($00) to 39 ($27) (Default=$00)
0x0F	2	Set Row	2nd byte is row 0 ($00) to 29 ($1D) (Default=$00)
0x10	1	Delete to SoL	Delete to start of line
0x11	1	Delete to EoL	Delete to end of line
0x12	1	Delete to SoS	Delete to start of screen
0x13	1	Delete to EoS	Delete to end of screen
0x14	1	Scroll Left	Scroll screen to the left replacing vacated columns with spaces
0x15	1	Scroll Right	Scroll screen to the right replacing vacated columns with spaces
0x16	1	Scroll Up	Scroll screen up replacing vacated rows with blank lines
0x17	1	Scroll Down	Scroll screen down replacing vacated rows with blank lines
0x18	2	Foreground Color	2nd byte is foreground color 0 ($00) to 255 ($FF) (Default=$FF)
0x19	2	Background Color	2nd byte is background color 0 ($00) to 255 ($FF) (Default=$00)
0x1A	2	Data Next	2nd byte data not command - Allows 0 ($00) to 31 ($1F), and 127 ($7F) as data
0x1B	1	ESC	Reserved for future escape code implementation
0x1C	1	Cursor Left	Move the cursor to the left
0x1D	1	Cursor Right	Move the cursor to the right
0x1E	1	Cursor Up	Move the cursor up
0x1F	1	Cursor Down	Move the cursor down
0x20	1	ASCII	Standard ASCII Characters
*	1	ASCII	Standard ASCII Characters
0x7E	1	ASCII	Standard ASCII Characters
0x7F	1	DELETE	Delete at cursor position
0x80	1	ASCII	Extended ASCII Characters
*	1	ASCII	Extended ASCII Characters
0xFF	1	ASCII	Extended ASCII Characters

Text Mode

In text mode, each byte sent to the terminal is interpreted and rendered as characters using the standard 8x8 pixel font. Each character cell can have its own foreground and background color by first setting the foreground and background colors before sending the next byte to be displayed. The terminal supports basic text operations such as cursor movement, line feed, carriage return, and clearing the screen.

The cursor can be controlled using the provided instructions, allowing it to be positioned using row and column commands, turned on or off, and set to solid or blinking mode.

In text mode, in order to display characters with ASCII values from 0 ($00) to 31 ($1F) or 127 ($7F), the "Data Next" instruction must first be sent to indicate that the next byte should be treated as data rather than a command.

Graphics Mode

The terminal can be switched into graphics mode to display pixel-based graphics. Data is then interpreted as the next byte row (0-7) in the 8x8 pixel block at the cursor position (column, row). After sending 8 bytes, the cursor automatically moves to the next column. After reaching the end of the row, it wraps to the beginning of the next row. After reaching the end of the screen, it wraps back to the top-left corner. If the cursor is moved manually using the set row and set column instructions, the next byte will be rendered at the top row of that position. In this way, the cursor can be positioned and then a continuous stream of bytes can be sent to the terminal to render pixel data.

Each byte that is sent can be individually colored using the foreground and background colors, enabling the creation of simple graphics and images.

In graphics mode, in order to send pixel data with ASCII values from 0 ($00) to 31 ($1F) or 127 ($7F), the "Data Next" instruction must first be sent to indicate that the next byte should be treated as pixel data rather than a command.

Installation

From NPM

npm install -g vtac-terminal

From Source

1. Clone the repository:

git clone https://github.com/acwright/VT-AC.git
cd VT-AC

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. (Optional) Link globally:

npm link

Usage

Basic Usage

Open the VT-AC terminal emulator with a path to the serial port (9600 baud, no parity, 8 data bits, 1 stop bit by default):

vtac -p /dev/ttyUSB0

Fullscreen Mode

vtac -p /dev/ttyUSB0 -f

With Scaling

vtac -p /dev/ttyUSB0 -s 4

Load Data File

VT-AC can load binary data files directly into the terminal before launch for parsing and display:

vtac -l /path/to/data.bin

Connect to Serial Port

vtac -p /dev/ttyUSB0 -b 115200 -a none -d 8 -t 1

Command Line Options

• -v, --version - Output the current version
• -h, --help - Display help information
• -p, --path <path> - Path to the serial port (e.g., /dev/ttyUSB0)
• -b, --baudrate <baudrate> - Baud rate (default: "9600")
• -a, --parity <parity> - Parity (default: "none")
• -d, --databits <databits> - Data bits (default: "8")
• -t, --stopbits <stopbits> - Stop bits (default: "1")
• -f, --fullscreen - Enable fullscreen mode (default: false)
• -s, --scale <scale> - Scale (default: "2")
• -l, --load <load> - Path to data file to load (e.g. /path/to/data.bin)

Development

Run in Development Mode

npm run build
node ./dist/index.js -p /dev/ttyUSB0

Release Build

git tag vX.Y.Z
git push origin main --tags
npm publish

Project Structure

VT-AC/
├── src/
│   ├── index.ts              # CLI entry point
│   └── VT-AC/
│       └── VT-AC.ts          # Core logic
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

TODO

• Implement escape sequences for extended control and ANSI support.
• Add support for additional character sets.
• 80 column mode.
• VT-100 terminal emulation.

License

MIT: https://github.com/acwright/VT-AC/blob/main/LICENSE

Credits

• Inspired By: http://searle.x10host.com/MonitorKeyboard/index.html
• Font Set: https://github.com/susam/pcface/tree/main/out/oldschool-bios-8x8