espterm_screenupdateformat_1.0.0.md

ESPTerm's binary objects

2B and 3B encoding

This encoding is used to safely transport numbers in a UTF-8 string. Essentially it's a Base127 format with each character incremented by 1, producing a sequence of ASCII characters 1-127, LSB first.

Eg.

• 1 -> 02h 01h in 2B encoding.
• 126 -> 7Fh 01h
• 127 -> 01h 02h
• 255 -> 02h 03h

3B encoding is analogous, except it uses 3 bytes (LSB MSB XSB)

Data objects - ESPTerm -> Browser

Screen labels object

Sets screen title and button labels

T
Screen title
01h
Button1 label
01h
Button2 label
01h
Button3 label
01h
Button4 label
01h
Button5 label

Bell message

Produces an audible beep in browser

Single byte message

B

Heartbeat

is sent every 1-2 seconds to indicate the connection is working

Single byte message

.

Screen content update

In the current implementation, this always encodes the entire screen content.

Later implementation will support partial updates.

S

2B(height)
2B(width)
2B(cursor_row, 0-based)
2B(cursor_column, 0-based)
2B(Screen_Status_Word)

--- here starts the content ---

-> char 32-255          : literal character (multi-byte UTF-8 code points allowed)
-> 01h 3B(SGR_word)     : set colors and attribs for following characters
-> 03h 2B(colors_byte)  : change colors for following characters
-> 04h 2B(attribs_byte) : change attribs for following characters
-> 02h 2B(n)            : repeat last character & style n times

Screen_Status_Word

Bitfield, little-endian.
LSb/LSB
 0 : cursor visible
 1 : cursor hanging at col W (outside screen)
 2 : cursor keys application mode
 3 : numpad keys application mode
 4 : function keys SS3 (Xterm) mode
 5 : track mouse clicks (disable context menu)
 6 : track mouse movement (disable selecting)
 7 : enable display of buttons under screen
 8 : enable display of menu links under screen
 9-15 : reserved
MSb/MSB

SGR_word

Two bytes, packed struct, little endian
LSb/LSB
0-7  : colors_byte
8-15 : attribs_byte
MSb/MSB

colors_byte

One byte:
LSb
0-3 : Fg color 0-16
4-7 : Bg color 0-16
MSb

attribs_byte

One byte:
LSb
0 : bold
1 : faint
2 : italic
3 : underline
4 : blink
5 : fraktur
6 : strike
7 : reserved
MSb

Xon, Xoff

Sent from ESPTerm for flood control during file upload. Xoff = stop sending, Xon = can continue

Single byte messages.

Xoff: -
Xon:  +

Data objects - Browser -> ESPTerm

Mouse report

m / p / r ... move, press, release
2B(row, 0-based)
2B(column, 0-based)
2B(button, 0-none, 1-left, 2-middle, 3-right, 4,5-wheel)
2B(modifiers_byte)

modifiers_byte

Single byte
LSb
0 : ctrl
1 : shift
2 : alt
3 : meta
4-7 : reserved
MSb

Action button press

b
0x01-0x05 : button, 1-based

Literal string typed / sent

s
Any number of bytes (max ~ 200)

[End of document]