Index: hid_remote/proto_parse.html
===================================================================
--- hid_remote/proto_parse.html (revision 33320)
+++ hid_remote/proto_parse.html (nonexistent)
@@ -1,38 +0,0 @@
-
-
-Protocol parser state machine of the reference implementation:
-
-Legend:
-
-
yellow boxes are states
-
blue arrows are optional features for a more tolerant parser
-
round nodes are actions that shall be taken
-
arrow with text: execute action or switch state if condition is true
-
arrow without text: do this if no other condition is met
-
-
Notes on the reference implementation
-The reference implementation builds a tree of nodes for the arguments.
-Each node is either a list or a text. A node has a pointer to its parent, its
-first child and its next sibling. While parsing list-of-lists, the parser
-keeps a current node. A new node is either added as the last sibling of
-the current node (new argument on a list) or as the first
-child of the current node (first argument of a new list when the list is
-open).
-
-When a list is closed, the parent of the current node becomes the
-new current node.
-
-When parsing a new message, the current node is NULL until the argument list
-is open; the new current node also becomes the argument tree root.
-If the argument tree root is closed, a newline shall follow, because that's
-how a message is terminated.
-
-The binary string part of the state machine has 2 more internal
-states:
-
-
a boolean indicating whether we are parsing the length or the string (before or after the '=')
-
an integer string length
-
-
-
-
Index: hid_remote/proto_parse.dot
===================================================================
--- hid_remote/proto_parse.dot (revision 33320)
+++ hid_remote/proto_parse.dot (nonexistent)
@@ -1,84 +0,0 @@
-digraph parse_state_macine {
-
-
-MSG [label="MSG:\nmessage lead-in\nor\nbetween\nmessages" shape=box style=filled fillcolor=yellow]
-COMMENT [label="COMMENT:\nskipping comment" shape=box style=filled fillcolor=yellow]
-CMD [label="CMD:\nparsing command name" shape=box style=filled fillcolor=yellow]
-TSTR [label="TSTR:\nparsing test string" shape=box style=filled fillcolor=yellow]
-BSTR [label="BSTR:\nparsing bin string" shape=box style=filled fillcolor=yellow]
-LIST [label="LIST:\nin list" shape=box style=filled fillcolor=yellow]
-ERROR [label="ERROR:\nbad input" shape=box style=filled fillcolor=red]
-
-######## MSG
-
-init [shape="diamond" style=filled fillcolor=yellow]
-init -> MSG
-
-msg_append [label="store 1st\ncommand char"]
-
-MSG -> COMMENT [label="input==#" color=blue]
-MSG -> MSG [label="input==\\r\\n\\t\nspace" color=blue]
-MSG -> ERROR [label="input==binary"]
-MSG -> msg_append [label="input==text"]
-msg_append -> CMD
-
-######## COMMENT
-
-COMMENT -> MSG [label="input==\\n" color=blue]
-COMMENT -> COMMENT [color=blue]
-
-
-######## CMD
-cmd_list_new [label="create new list\nmake it arg tree\nroot and current"]
-cmd_list_new -> LIST
-cmd_append [label="append a character\nto command name"]
-cmd_append -> CMD [label="command name length\nis less than 16"]
-cmd_append -> ERROR [label="command name length\nis more than 16"]
-CMD -> cmd_list_new [label="input==({"]
-CMD -> ERROR [label="input==binary"]
-CMD -> cmd_append [label="input==text"]
-
-######## LIST
-got_msg [label="message fully parsed\nexecute message" style=filled fillcolor=cyan]
-got_msg -> MSG
-pop [label="pop:\ncurrent_list = current_list->parent"]
-pop -> got_msg [label="input=\\n\nand\ncurrent_list == NULL\n(arg root closed)"]
-pop -> ERROR [label="input!=\\n\nand\ncurrent_list == NULL\n(unbalanced parenthesis)"]
-pop -> LIST
-push [label="push:\create new list\nappend it as current's sibling\nmake it current"]
-push->LIST
-new_str [label="create a new bin or text string\nnode and append it to\nthe current list"]
-new_str -> tstr_append [label="current is generic list"]
-new_str -> bstr_append [label="current is binary list"]
-
-LIST -> pop [label="input==)}"]
-LIST -> push [label="input==({"]
-LIST -> LIST [label="input==space\n(ignore)"]
-LIST -> ERROR [label="input!=\\n and current == NULL\n(unbalanced parenthesis)"]
-LIST -> new_str [label="input==text"]
-
-######## TSTR
-str_fin [label="finish current string\n"]
-str_fin -> LIST
-str_fin_pop [label="finish current string\n"]
-str_fin_pop -> pop
-tstr_append [label="append to current string\n"]
-tstr_append -> ERROR [label="string length > 16"]
-tstr_append -> TSTR
-TSTR -> str_fin [label="input==space"]
-TSTR -> str_fin_pop [label="input==)}"]
-TSTR -> ERROR [label="input==binary"]
-TSTR -> tstr_append [label="input==text"]
-
-######## BSTR
-read_base64 [label="store next digit\nof string length"]
-read_base64 -> BSTR
-bstr_append -> BSTR
-BSTR -> read_base64 [label="before the ="]
-BSTR -> bstr_append [label="after the ="]
-BSTR -> str_fin_pop [label="last char of the string"]
-
-######## ERR
-ERROR -> ERROR [label="can't recover"]
-
-}
Index: hid_remote/proto_high.html
===================================================================
--- hid_remote/proto_high.html (revision 33320)
+++ hid_remote/proto_high.html (nonexistent)
@@ -1,237 +0,0 @@
-
-
-
remote HID protocol, high level
-
-
reference
-
-
ver(protver)
-Sends the protocol version the server will speak. If the client doesn't
-support that version, it should break the connection.
-
-Arguments:
-
-
protver: an integer value; 1 for the current version
-
-
-
unit(abbrev)
-Sends the coordinate unit used in subsequent communication. This is not
-necessarily the unit used for displaying values on the user interface,
-but the unit used to interpret numeric coordinate values sent in commands.
-
-Arguments:
-
-
abbrev: unit name abbreviation; e.g. mm or nm or mil
-
-
-
ready()
-Informs the client that the server is ready to start the session. The
-client needs to answer with a Ready() message before the server proceeds.
-
-Arguments: none.
-
-
-
brddim(w h)
-Announce board dimensions. Some layers may extend beyond the board.
-
-Arguments:
-
-
w: width (x size) in coordinate units
-
h: height (y size) in coordinate units
-
-
-
inval(x1 x2 y1 y2)
-Invalidate a rectangular section of the screen; the client should redraw
-this area. Clients implementing their own mechanism to keep track on
-drawing are free to ignore these requests
-
-Arguments:
-
-
x1: left coordinate
-
x2: right coordinate
-
y1: top coordinate
-
y2: bottom coordinate
-
-
-
inval()
-Same as inval(x1 x2 y1 y2) but invalidates the whole screen.
-
-Arguments: none
-
-
newlg(name group_id flags)
-Create a new layer group.
-
-Arguments:
-
-
name: name of the layer group - names are not unique
-
group_id: unique group ID (decimal integer, may be large)
-
flags: a list of 3 items: location, purpose and properties. Each item is a list of values (or an empty list).
-
-Creates the top assembly virtual layer with ID 16777219 with the name
-of "topassembly"
-
-
newly(name layer_id group_id)
-Create a new layer within an existing layer group.
-
-Arguments:
-
-
name: name of the layer (can be empty, not unique)
-
layer_id: unique ID of this layer (decimal integer, may be large)
-
group_id: reference to a previously created layer group which this layer is part of
-
-
-Example:
-
-newly(soldergnd 3 11)
-
-Creates a layer 3 called "soldergnd" in group 11.
-
-
setlg(group_id is_empty purpose)
-Inform the client that the next set of drawing commands are for a specific
-layer group. (Note: the reason for announcing groups and not layers:
-all layers in that group are drawn at once; visibility
-of layers within the same group are switched together.)
-
-Arguments:
-
-
group_id: unique ID of the layer group
-
is_empty: 1 if the layer group may be empty, 0 if the layer is not empty (TODO: this bit is not 100% reliable yet)
-
purpose: layer group purpose field (usefil in mech/doc groups)
-
-
-
makeGC()
-Request the client to make a new graphical context. The client should
-allocate a GC and return an integer ID using the MadeGC(ID) message.
-The ID uniquely identifies the GC; it should be small positive integer
-(between 0 and 31 for now).
-
-Arguments: none
-
-
delGC(ID)
-Inform the client that a given GC is not needed anymore. The server
-will not reference the GC again and the GC can be destroyed (but graphics
-drawn on the screen should not be affected). The ID may be reused by the
-client in a subsequent madeGC() message).
-
-Arguments:
-
-
ID: integer ID of the GC
-
-
-
clr(gci colorstring)
-Change the color subsequent drawing commands of a given GC will use.
-
-Arguments:
-
-
gci: ID of the GC
-
colorstring: name of the color, specified in the usual "web" format: #rrggbb (with 3 hex numbers)
-
-
-
cap(gci style)
-Set the line ending cap style. Note: the cap extends half-line-width beyond
-the end coordinates, e.g. the end point of a line is the center of the round-cap
-circle.
-
-Arguments:
-
-
gci: ID of the GC
-
style: r for round cap (circle), s for square cap, b for beveled (octagon)
-
-
-
-
linwid(gci width)
-Sets line width (pen tip diameter).
-
-Arguments:
-
-
gci: ID of the GC
-
width: diameter of the circular aperture of the pen in coord units
-
-
-
setxor(gci state)
-Sets whether to perform "xor-drawing" for subsequent drawing commands in
-the selected GC.
-
-Arguments:
-
-
gci: ID of the GC
-
xor: 0 means normal drawing, 1 means xor drawing
-
-
-
-
line(gci x1 y1 x2 y2)
-Draw a line using the current GC. The line inherits line width, color
-and cap style from the GC.
-
-Arguments:
-
-
gci: ID of the GC
-
x1: 1st endpoint's X coord (in coord units)
-
y1: 1st endpoint's Y coord (in coord units)
-
x2: 2nd endpoint's X coord (in coord units)
-
y2: 2nd endpoint's Y coord (in coord units)
-
-
-
rect(gci x1 y1 x2 y2 filled)
-Draw a rectangle. The rectangle inherits only color from the GC.
-
-Arguments:
-
-
gci: ID of the GC
-
x1: 1st corner X coord (in coord units); x1 <= x2
-
y1: 1st corner Y coord (in coord units); y1 <= y2
-
x2: 2nd corner X coord (in coord units)
-
y2: 2nd corner Y coord (in coord units)
-
filled: 1 if the rectangle should be filled; a non-filled rectangle is a frame of 1 pixel wide lines
-
-
-
-
fcirc(gci cx cy r)
-Draw a filled circle. The circle inherits only color from the GC.
-
-Arguments:
-
-
gci: ID of the GC
-
cx1: center X coord (in coord units)
-
cy1: center Y coord (in coord units)
-
r: radius (in coord units)
-
-
-
poly(gci len ptlist)
-Draw a filled polygon. The polygon inherits only color from the GC.
-
-Arguments:
-
-
gci: ID of the GC
-
len: number of contour points
-
ptlist: an ordered list of (x y) coordinates (all in coord units)
-
-
-
umask(m)
-"use mask" m. The server uses this message to make an announcement before it
-starts drawing certain things.
-
-Arguments:
-
-
m: mask name:
-
-
off: flush the buffer and return to non-mask operation.
-
-where text-string is a command and generic-list is a list and holds
-the arguments of. The command name can not start with a hash mark ('#') and
-can not be empty. The list is the argument tree of the command.
-
-As a special exception, a line may start with a hash mark ('#') to indicate
-a comment. Characters up to the first newline are ignored.
-
-Optional: a tolerant parser also accepts empty lines and whitespace before
-a message.
-
-The language has two type of lists: generic and binary.
-A generic list is wrapped in parenthesis () and its children are:
-
-
text-string,
-
generic-list,
-
binary-list.
-
-A binary-list is wrapped in braces {} and its children are:
-
-
binary-string,
-
binary-list.
-
-
-Any list can be empty. There's no whitespace after the opening token and
-before the closing token, so the empty generic-list and the empty binary-list
-are written as, respectively:
-
-()
-{}
-
-Subsequent fields of a list has a single space in between, for
-separation (this is an intentional redundancy for a binary-list).
-
-Note: a generic-list can host text and binary children, but a
-binary list can not host only binary children. This means if a node
-of the parse tree is a binary list, the subtree will contain only binary nodes.
-
-A text-string contains only English alphanumeric characters (A..Z, a..z,
-0..9), underscores (_), plus and minus signs (+, -) periods (.) and
-the hash mark ('#') and is at most 16 characters long.
-
-A binary string encodes the length of the payload in base64 (A..Z, a..z, +, /),
-has a '=' for separator then the payload in binary format. For example
-
-F=hello
-
-means the 5 characters long string "hello". The maximum size of the base64
-encoded length field is 5, thus the longest binary data that can be
-packed in a single field is 1 gigabyte.
-
-
Examples
-
-
empty-argument messages
-
-hello()\n
-foo{}\n
-
-
-
single-argument messages
-Text and binary alternative for the same content:
-
-hello(world)\n
-hello{F=world}\n
-
-
-
multi-argument messages
-Text and binary alternative for the same content:
-
-print(hello world !)\n
-print{E=hello F=world B=!}\n
-
-
-Note: using space between list items; don't space
-before the first or after the last argument. Always emit one space between
-any two list items.
-
-
lists in list
-Text and binary alternatives for the same content:
-
-The subtree assumed in this fictional message is two x;y coordinate pairs
-and a line width. In other words the arguments of line is a list (start
-point), another list (end point) and a scalar (width).
-
-Since all data comply to the text-string token format,
-the first, simplest format is recommended. The other 4 lines demonstrate all
-other valid variants.
-
-It is important to note that there are constraints (derived from
-the grammar) on choosing which list items can be encoded in binary:
-
-
a binary-string can be only on a binary-list
-
a text-string can be only on a generic-list
-
a generic-list can not be only under a binary-list
-
-Legend:
-