StepCtrl UI Protocol (early spec)

General Goals:
* Will send relevant mouse and keyboard events.
* Will recieve console text.
* Will implement basic File Transfer.
** For now will focus on transferring G-Code Programs.
** A more general purpose mechanism may be added later.


=== Overview ===

The basic protocol will be UDP Based, with the server at port 16961. The server in this context will refer to the CNC Controller, with the user-side client connecting to the server.

The UI will run on the server, with the screen image being streamed to the client. The screen will use a color-cell format, nominally at 80x25.

Messages will also be scrambled using the NodeID as a key. The NodeID will be be externally agreed upon between the endpoints.

This key will obfuscate the datagrams, and also help avoid interaction with non-paired nodes.


=== Message Formats ===

Messages will use a TLV format.
As-is network-protocol tradition, will use big-endian.


Messages will start with a 16-bit hash and a message size, in effect the message is itself in TLV format, with the message has as the tag.

TLV Format (Basic):
  u16 tag;	//0xA000..0xFFFF
  u16 len;	//up to 32K

Tags between 0xA000 and 0xFFFF will be TWOCC tags.

Tag values in the range of 0x0000 to 0x7FFF will be the start of 32-bit FOURCC values. Values in the range of 0x8000..0x9FFF are reserved for larger tags.

The length is nominally 16 bits, with a size limit of 32K.
The length will include both the size of the tag as well as the size of the payload.

If the length is 0x8000 to 0xBFFF, it will be interpreted as the high word of a 32-bit length (up to 1GB). 0xC000..0xDFFF will start a 48-bit length (up to 32TB).

For the basic UDP protocol, only 16-bit tags and lengths are allowed.


Messages:
  0xCD00, Reserved

  0xCD01, Console Delta (Basic)
  0xCD02, ASCII/ANSI
    SV->CL: Text to display on screen.
    CL->SV: Mouse + Keyboard.
  0xCD03, Connect
  0xCD04, KeyMap

  0xFD01, File Data
  0xFD02, File Data ACK
  0xFD03, Request File


=== KeyMap ===

Will transfer 32 bytes of data representing a bitmap for which keys are currently pressed.

The first 16 bits of the message will be used as a sequence number.
The following 16 bits will give a status code.

The remaining 32 bytes will give a keypress bitmap. This bitmap will be interpreted in LSB-first order.

Bits 0..127 will be represent the keys interpreted in ASCII order.
Bits 128..255 will be used for the remaining (non-ASCII) keys.


=== Console Memory ===

The console will be organized as 80x25 cells, each composed of 8 DWORDs.
* DWord 0: Text Cell or Color Endpoints
* DWord 1: Color Endpoints (Usually)
* DWord 2/3: Color Endpoints
* DWord 4..7: Pixel Bits


Text Cells will nominally follow the layout (0.0):
* (31:30): 00 (Text Cell)
* (29:28): 00 (RGB6)
* (27:22): ColorA
* (21:16): ColorB
* (15:10): Attribute Flags
* ( 9: 8): Font
* ( 7: 0): Glyph

But, may also follow the layout (0.2):
* (31:30): 00 (Text Cell)
* (29:28): 10 (RGB9)
* (27:19): ColorA
* (18:10): ColorB
* ( 9: 8): Font
* ( 7: 0): Glyph

The latter mode has more colors available, but may not have attribute flags.

Fonts:
* 0: Codepage 437
* 1: Various Block Drawing Characters
* 2: Codepage 1252
* 3: Dynamic


Pixel Bits will represent either an 8x8x2 cell, or an 8x16x1 cell.
Each dword will represent a subcell (4x4x2 or 4x8x1), with the cells organized in raster order (4=UL, 5=UR, 6=LL, 7=LR).

Pixels will be organized as 2-bit pairs in raster order starting from the MSB.
With 4x8 subcells, the high bit of each 2-bit pair will represent the even scanline, and the low bit will represent the odd scanline.

Color Endpoints for color-cell blocks will be in YVU654 order:
* (14: 9): Y
* ( 8: 4): V (Cr)
* ( 3: 0): U (Cb)

This may be unpacked and converted to RGB for display.

Alternately, the server may opt to use 15-bit RGB555 instead.
 (15:10): R
 ( 9: 5): G
 ( 4: 0): B

The high 2 bits of Word 0 and 1 will be used to encode the Cell Type.

High bits of Word 0:
* 00(0)=Text Cell (only uses Word 0, 32 bits)
* 01(1)=Limited Graphics Cell Formats (Words 0 and 1, 64 bits)
* 10(2)=Medium Graphics Cell Formats (Words 0..3, 128 bits)
* 11(3)=Full Graphics Cell Formats (Words 0..7, 256 bits)

In Mode 3, the high 2 bits of Word 1 give the subtype:
* 00(0)=Reserved
* 01(1)=8x16x1 (4x 4x8x1)
* 10(2)=4:2:0, 4x8x2 (2x 4x4x2)
* 11(3)=8x8x2 (4x 4x4x2)

In Mode 3, the low 30 bits in dwords 0..3 are interpretes as pairs of color endpoints in YVU654 or RGB555. These endpoints are in the same order as their corresponding pixel blocks.

In sub-mode 2, only words 6 and 7 are used for pixel data. The 8 color endpoint values are interpreted as color centers, with words 4 and 5 giving Ymax-Ymin values (as a series of 7 bit entries).

The modes will thus give the effective screen resolutions at 80x25:
* 0: Reserved
* 1: 640x400
* 2: 320x200
* 3: 640x200


=== Console Delta ===

First Word of the Console Delta message will be interpreted as a sequence number.

The remainder of the message will be interpreted as a series of 16-bit words encoding changes to the console buffer.

Consists of a series of 16-bit tags:
* 0000..00FF: Cell Character
**   Updates the text character of the cell
**   Automatically advances to next cell

* 0100..01FF: Delta-Mask DWords
**   Gives a mask of which DWords have changed
**   Followed by the DWord values
**   Automatically advances to next cell

* 0200..02FF: Run of character bytes
**   Only the cell characters have changed
**   Run length is in terms of pairs of bytes.
**   Uses 0200 as a special-case, encoding a sequence number.

* 0300..03FF: Run of character low DWords
**   The low DWord of each cell has changed

* 2000..2FFF: Cell DWord, Mode 0.0 (RGB6)
* 3000..3FFF: Cell DWord, Mode 0.2 (RGB9)
**   Update the low DWord of the cell (Character+Attribute)
**   Automatically advances to next cell
* 4000..7FFF: Jump to screen position (cell index).


=== File Data ===

Starts with a DWORD encoding a file handle and the sector offset.
* (31:24)=Handle
* (   23)=End Of Transfer
* (22: 0)=Sector Offset

This is followed by 512 or 1024 bytes of file data.
The payload may be smaller at the end of the file.

End Of Transfer:
* Set by sender if all preceding blocks have been transfered and acknowledged.
* If reciever sees this, it can safely close the file.
** Any following blocks recieved for this handle should be ignored.

The sector offset will be in terms of 512 byte sectors.


The File Data ACK message contains the request DWORD and a status WORD, but does not contain payload. It is used by the reciever to inform the sender which blocks have been recieved thus far. The default 'ACK' status will be 0x0001.

The sender will transmit blocks until it has seen acknowldegements for all blocks, and will then terminate the transfer. Transfers may be done in either a bursty or ping-pong style.


=== Request File ===

Request file to be sent or recieved.
Nominally, these requests will be sent from the server to the client.

Will contain a 32-bit DWORD:
* (31:24): File handle to use.
* (23:20): Flags
* (19:16): Request Type
* (15:14): File Type
* (13: 0): File Number

The word will be followed by a status code whose meaning depends on the request type.

Program Type:
* 00: G-Code / NC Program.
* 01: Named Handle (Generic File)
Request Type:
* 0: None
* 1: GET, Request a file to be sent.
* 2: PUT, Request to send a file.
* 3: STATUS, Response code for a request.


For G-Code programs, the program number will range from 0000 to 9999.
These will come from a specific directory, and will follow the form "Oxxxx.nc"

This directory will be specific to the transfer of CNC programs.


Named handles will correspond to indices into a name-table.
A mechanism may be provided to transfer names.