• *Communication UART (Rx, Tx)* can be configured in the System Settings.
• *Boot log and debug messages* are available on pin *GPIO2* (P2) at 115200\,baud, 1 stop bit, no parity. Those messages may be disabled through compile flags.
• *Loopback test*: Connect the Rx and Tx pins with a piece of wire. Anything you type in the browser should appear on the screen. Set _Parser Timeout = 0_ in Terminal Settings to be able to manually enter escape sequences.
• There is very little RAM available to the webserver, and it can support at most 4 connections at the same time. Each terminal session (open window with the terminal screen) uses one persistent connection for screen updates. *Avoid leaving unused windows open*, or either the RAM or connections may be exhausted.
• *For best performance*, use the module in Client mode (connected to external network) and minimize the number of simultaneous connections. Enabling AP consumes extra RAM because the DHCP server and Captive Portal DNS server are started.
• In AP mode, *check that the WiFi channel used is clear*; interference may cause flaky connection. A good mobile app to use for this is WiFi Analyzer (Google Play). Adjust the hotspot strength and range using the _Tx Power setting_.
• Hold the BOOT button (GPIO0 to GND) for ~1 second to force enable AP. Hold it for ~6 seconds to restore default settings. (This is indicated by the blue LED rapidly flashing). Default settings can be overwritten in the System Settings.

ESPTerm emulates VT102 (pictured) with some additions from later VT models and Xterm. All commonly used attributes and commands are supported. ESPTerm is capable of displaying ncurses applications such as _Midnight Commander_ using _agetty_.

ESPTerm accepts UTF-8 characters received on the communication UART and displays them on the screen, interpreting some codes as Control Characters. Those are e.g. _Carriage Return_ (13), _Line Feed_ (10), _Tab_ (9), _Backspace_ (8) and _Bell_ (7).

Escape sequences start with the control character _ESC_ (27), followed by any number of ASCII characters forming the body of the command.

Nomenclature & Command Types

Examples on this help page use the following symbols for special characters and command types:\\ (spaces are for clarity only, _DO NOT_ include them in the commands!)

There are also some other commands that don't follow the CSI, SGR or OSC pattern, such as `\e7` or `\e#8`. A list of the most important escape sequences is presented in the following sections.

The initial screen size, title text and button labels can be configured in Terminal Settings.

Screen updates are sent to the browser through a WebSocket after some time of inactivity on the communication UART (called "Redraw Delay"). After an update is sent, at least a time of "Redraw Cooldown" must elapse before the next update can be sent. Those delays are used is to avoid burdening the server with tiny updates during a large screen repaint. If you experience issues (broken image due to dropped bytes), try adjusting those config options. It may also be useful to try different baud rates.

All text attributes are set using SGR commands like `\e[10;20;30m`, with up to 10 numbers separated by semicolons. To restore all attributes to their default states, use SGR 0: `\e[0m` or `\e[m`.

Those are the supported text attributes SGR codes:

Style	Enable	Disable
Bold	1	21, 22
Faint	2	22
Italic	3	23
Underlined	4	24
Blink	5	25
Inverse	7	27
Striked	9	29
𝔉𝔯𝔞𝔨𝔱𝔲𝔯	20	23

Keyboard

The user can input text using their keyboard, or on Android, using the on-screen keyboard which is open using a button beneath the screen. Supported are all printable characters, as well as many control keys, such as arrows, _Ctrl+letters_ and function keys. Sequences sent by function keys are based on VT102 and Xterm.

The codes sent by _Home_, _End_, _F1-F4_ and cursor keys are affected by various keyboard modes (_Application Cursor Keys_, _Application Numpad Mode_, _SS3 Fn Keys Mode_). Some can be set in the Terminal Settings, others via commands.

Here are some examples of control key codes:

Key	Code	Key	Code
Up	`\e[A`	F1	`\eOP`
Down	`\e[B`	F2	`\eOQ`
Right	`\e[C`	F3	`\eOR`
Left	`\e[D`	F4	`\eOS`
Home	`\eOH`	F5	`\e[15~`
End	`\eOF`	F6	`\e[17~`
Insert	`\e[2~`	F7	`\e[18~`
Delete	`\e[3~`	F8	`\e[19~`
Page Up	`\e[5~`	F9	`\e[20~`
Page Down	`\e[6~`	F10	`\e[21~`
Enter	`\r` (13)	F11	`\e[23~`
Ctrl+Enter	`\n` (10)	F12	`\e[24~`
Tab	`\t` (9)	ESC	`\e` (27)
Backspace	`\b` (8)	Ctrl+A..Z	ASCII 1-26

Action buttons

The blue buttons under the screen send ASCII codes 1, 2, 3, 4, 5, which incidentally correspond to _Ctrl+A,B,C,D,E_. This choice was made to make button press parsing as simple as possible.

Mouse

ESPTerm implements standard mouse tracking modes based on Xterm. Mouse tracking can be used to implement powerful user interactions such as on-screen buttons, draggable sliders or dials, menus etc. ESPTerm's mouse tracking was tested using VTTest and should be compatible with all terminal applications that request mouse tracking.

Mouse can be tracked in different ways; some are easier to parse, others more powerful. The coordinates can also be encoded in different ways. All mouse tracking options are set using option commands: `CSI ? _n_ h` to enable, `CSI ? _n_ l` to disable option _n_.

Mouse Tracking Modes

All tracking modes produce three numbers which are then encoded and send to the application. First is the _event number_ N, then the _X and Y coordinates_, 1-based.

Mouse buttons are numbered: 1=left, 2=middle, 3=right. Wheel works as two buttons (4 and 5) which generate only press events (no release).

Mouse Report Encoding

The following encoding schemes can be used with any of the tracking modes (except Focus tracking, which is not affected).

The coordinates are 1-based, origin is top left. The cursor can move within the entire screen, or in the active Scrolling Region if Origin Mode is enabled.

After writing a character, the cursor advances to the right. If it has reached the end of the row, it stays on the same line, but writing the next character makes it jump to the start of the next line first, scrolling up if needed. If Auto-wrap mode is disabled, the cursor never wraps or scrolls the screen.

*Legend:* Italic letters such as _n_ are ASCII numbers that serve as arguments, separated with a semicolon. If an argument is left out, it's treated as 0 or 1, depending on what makes sense for the command.

Movement

Code	Meaning
\e[nA \\ \e[nB \\ \e[nC \\ \e[nD	Move cursor up (`A`), down (`B`), right (`C`), left (`D`)
\e[nF \\ \e[nE	Go _n_ lines up (`F`) or down (`E`), start of line
\e[rd \\ \e[cG \\ \e[r;cH	Go to absolute position - row (`d`), column (`G`), or both (`H`). Use `\e[H` to go to 1,1.
`\e[6n`	Query cursor position. Sent back as `\e[r;cR`.

Save / restore

Code	Meaning
\e[s \\ \e[u	Save (`s`) or restore (`u`) cursor position
\e7 \\ \e8	Save (`7`) or restore (`8`) cursor position and attributes

Scrolling Region

Code	Meaning
`\e[a;br`	Set scrolling region to rows _a_ through _b_ and go to 1,1. By default, the scrolling region spans the entire screen height. The cursor can leave the region using absolute position commands, unless Origin Mode (see below) is active.
\e[?6h \\ \e[?6l	Enable (`h`) or disable (`l`) Origin Mode and go to 1,1. In Origin Mode, all coordinates are relative to the Scrolling Region and the cursor can't leave the region.
\e[nS \\ \e[nT	Move contents of the Scrolling Region up (`S`) or down (`T`), pad with empty lines of the current background color.

Tab stops

Code	Meaning
`\eH`	Set tab stop at the current column. There are, by default, tabs every 8 columns.
\e[nI \\ \e[nZ	Advance (`I`) or go back (`Z`) _n_ tab stops or end/start of line. ASCII _TAB_ (9) is equivalent to \e[1I
\e[0g \\ \e[3g \\	Clear tab stop at the current column (`0`), or all columns (`3`).

Other options

Code	Meaning
\e[?7h \\ \e[?7l	Enable (`h`) or disable (`l`) cursor auto-wrap and screen auto-scroll
\e[?25h \\ \e[?25l	Show (`h`) or hide (`l`) the cursor

Legend: Italic letters such as _n_ are ASCII numbers that serve as arguments, separated with a semicolon. If an argument is left out, it's treated as 0 or 1, depending on what makes sense for the command.

Code	Meaning
`\e[mJ`	Clear part of screen. _m_: 0 - from cursor, 1 - to cursor, 2 - all
`\e[mK`	Erase part of line. _m_: 0 - from cursor, 1 - to cursor, 2 - all
`\e[nX`	Erase _n_ characters in line.
\e[nL \\ \e[nM	Insert (`L`) or delete (`M`) _n_ lines. Following lines are pulled up or pushed down.
\e[n@ \\ \e[nP	Insert (`@`) or delete (`P`) _n_ characters. The rest of the line is pulled left or pushed right. Characters going past the end of line are lost.

ESPTerm implements Alternate Character Sets as a way to print box drawing characters and special symbols. A character set can change what each received ASCII character is printed as on the screen (eg. "{" is "π" in codepage `0`). The implementation is based on the original VT devices. Since ESPTerm also fully supports UTF-8, you can probably ignore this feature and use Unicode directly. It's added for compatibility with some programs that use this.

The following codepages are implemented:

• `B` - US ASCII (default)
• `A` - UK ASCII: # replaced with £
• `0` - Symbols and basic line drawing (standard DEC alternate character set)
• `1` - Symbols and advanced line drawing (based on DOS codepage 437)

To see what character maps to which symbol, look in the source code or try it. All codepages use codes 32-127, 32 being space.

There are two character set slots, G0 and G1. Those slots are selected as active using ASCII codes Shift In and Shift Out (those originally served for shifting a red-black typewriter tape). Each slot (G0 and G1) can have a different codepage assigned. G0 and G1 and the active slot number are saved and restored with the cursor and cleared with a screen reset (\ec).

The following commands are used:

Code	Meaning
`\e(x`	Set G0 = codepage x
`\e)x`	Set G1 = codepage x
_SO_ (14)	Activate G0
_SI_ (15)	Activate G1

It's possible to dynamically change the screen title text and action button labels. Setting an empty label to a button makes it look disabled. The buttons send ASCII 1-5 when clicked. Those changes are not retained after restart.

Code	Meaning
`\ec`	Clear screen, reset attributes and cursor. The screen size, title and button labels remain unchanged.
`\e[5n`	Query device status, ESPTerm replies with `\e[0n` "device is OK". Can be used to check if the terminal has booted up and is ready to receive commands.
_CAN_ (24)	This ASCII code is not a command, but is sent by ESPTerm when it becomes ready to receive commands. When this code is received on the UART, it means ESPTerm has restarted and is ready. Use this to detect spontaneous restarts which require a full screen repaint.
`\e]0;title\a`	Set screen title (this is a standard OSC command)
\e]81;btn1\a \\ \e]82;btn2\a \\ \e]83;btn3\a \\ \e]84;btn4\a \\ \e]85;btn5\a \\	Set button 1-5 label - eg.`\e]81;Yes\a` sets the first button text to "Yes".
`\e[8;r;ct`	Set screen size (this is a command borrowed from xterm)