Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
en:netzer:commandinterface [2014/01/04 17:55] svesch [Command interface (Draft)] |
en:netzer:commandinterface [2014/02/09 14:32] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | <WRAP clear></WRAP> | ||
+ | ====== Command interface ====== | ||
+ | |||
+ | The command interface can be used for accessing Netzer with client programs. | ||
+ | |||
+ | |||
+ | ===== Functional principle ===== | ||
+ | |||
+ | The command interface is message based, i.e. defines the format of the exchanged messages between Netzer and a client program. | ||
+ | The communication channel is mostly independent from the message. | ||
+ | Hence, multiple channels are implemented from where the command interface can be used. | ||
+ | Which channels are implemented depends on the Netzer firmware version. | ||
+ | Possible channels are the [[commandserver|command server]], [[actioncgi|CGI]] and [[websockets|WebSocket]]. | ||
+ | |||
+ | |||
+ | One message consists of a command and a value. | ||
+ | |||
+ | Messages without a value can be used for reading parameters. | ||
+ | |||
+ | <WRAP column 30%> | ||
+ | **Client to Netzer** | ||
+ | <code>sup</code> | ||
+ | </WRAP><WRAP column 30%> | ||
+ | **Netzer to client** | ||
+ | <code>{"s":{"u":{"p":"0"}}}</code> | ||
+ | </WRAP> | ||
+ | <WRAP clear></WRAP> | ||
+ | |||
+ | Messages with value to write. | ||
+ | |||
+ | <WRAP column 30%> | ||
+ | **Client to Netzer** | ||
+ | <code>sup=1</code> | ||
+ | </WRAP><WRAP column 30%> | ||
+ | **Netzer to client** | ||
+ | <code>{"s":{"u":{"p":"1"}}}</code> | ||
+ | </WRAP> | ||
+ | <WRAP clear></WRAP> | ||
+ | |||
+ | |||
+ | ===== The command tree ===== | ||
+ | |||
+ | The command tree is the base for all commands. | ||
+ | A command is a (not empty) sequence of alphanumeric characters (lower case letters and numbers) which describes a path within the command tree. | ||
+ | {{ ci_example_plain.svg |Example of a command tree}} | ||
+ | |||
+ | Write commands (messages with value) have to end on a tree leaf (i.e. identify exactly one parameter), because only one parameter can be written at once. | ||
+ | |||
+ | Read commands also can also end at an inner node of the command tree. | ||
+ | Hence, all nodes beneath the read node can be read at once. | ||
+ | |||
+ | <WRAP center round box 90%> | ||
+ | <WRAP column 45%> | ||
+ | {{ci_example_leaf.svg|Command ends at a leaf}} | ||
+ | |||
+ | **Read:** | ||
+ | <WRAP column 40%> | ||
+ | **Client to Netzer** | ||
+ | <code>sup</code> | ||
+ | </WRAP><WRAP column 40%> | ||
+ | **Netzer to client** | ||
+ | <code>{"s":{"u":{"p":"0"}}}</code> | ||
+ | </WRAP><WRAP clear></WRAP> | ||
+ | |||
+ | **Write:** | ||
+ | <WRAP column 40%> | ||
+ | **Client to Netzer** | ||
+ | <code>sup=1</code> | ||
+ | </WRAP><WRAP column 40%> | ||
+ | **Netzer to client** | ||
+ | <code>{"s":{"u":{"p":"1"}}}</code> | ||
+ | </WRAP><WRAP clear></WRAP> | ||
+ | |||
+ | </WRAP><WRAP column 45%> | ||
+ | {{ci_inner_node.svg|Command ends at an inner node}} | ||
+ | |||
+ | **Read:** | ||
+ | <WRAP column 40%> | ||
+ | **Client to Netzer** | ||
+ | <code>su</code> | ||
+ | </WRAP><WRAP column 40%> | ||
+ | **Netzer to client** | ||
+ | <code>{"s":{"u":{"b":"5","p":"0"}}}</code> | ||
+ | </WRAP><WRAP clear></WRAP> | ||
+ | |||
+ | **Write:** | ||
+ | |||
+ | Not supported | ||
+ | |||
+ | </WRAP> | ||
+ | |||
+ | </WRAP> | ||
+ | |||
+ | |||
+ | ==== Edges with numerical values ==== | ||
+ | |||
+ | Numeric edges are used as represenation for continuous numeric intervals. | ||
+ | Hence, adding each single number as a command tree node is prevented. | ||
+ | Such edges can be recognized by square brackets which stand for the possible hexadecimal interval for this edge. | ||
+ | |||
+ | <WRAP center round box 60%> | ||
+ | {{ci_example_interval.svg|Red: Edge with numerical value}} | ||
+ | |||
+ | For the edge with //[0-3]// the hexadecimal numbers ''0'', ''1'', ''2'' and ''3'' are possible. | ||
+ | </WRAP> | ||
+ | |||
+ | Multiple numerical number edges within a command are interpreted as continuous interval. | ||
+ | The interval limits are build through the concatenation of the numbers within the square brackets. | ||
+ | |||
+ | <WRAP center round box 60%> | ||
+ | The path leads via two edges with //[0-1]// and //[0-c]//. | ||
+ | This means the matematical interval ''[0x00, 0x1c]''. | ||
+ | |||
+ | The following commands are possible: ''00'', ''01'', ''02'', ''03'', ''04'', ''05'', ''06'', ''07'', ''08'', ''09'', ''0a'', ''0b'', ''0c'', ''0d'', ''0e'', ''0f'', ''10'', ''11'', ''12'', ''13'', ''14'', ''15'', ''16'', ''17'', ''18'', ''19'', ''1a'', ''1b'' and ''1c''. | ||
+ | |||
+ | </WRAP> | ||
+ | |||
+ | |||
+ | ===== Channel specific commands ===== | ||
+ | |||
+ | Beyond the command tree, which depends on the Netzwer firmware, also channel specific commands may exist. | ||
+ | Those commands always start with ''z''. | ||
+ | |||
+ | |||
+ | ===== Messages from client to Netzer ===== | ||
+ | |||
+ | Messages from client to Netzer consist of a string containing the command and an optional value like ''command=value''. | ||
+ | Per message only one parameter can be written. | ||
+ | |||
+ | The exact format syntax for connecting command and value depends on the used channel. But normally it is the format ''command=value''. | ||
+ | <WRAP center round box 60%> | ||
+ | Example WebSocket channel | ||
+ | <WRAP column 30%> | ||
+ | **Client to Netzer** | ||
+ | <code>sup=1</code> | ||
+ | </WRAP><WRAP column 30%> | ||
+ | **Netzer to client** | ||
+ | <code>{"s":{"u":{"p":"1"}}}</code> | ||
+ | </WRAP> | ||
+ | <WRAP clear></WRAP> | ||
+ | </WRAP> | ||
+ | |||
+ | |||
+ | ===== Messages from Netzer to client ===== | ||
+ | |||
+ | Messages from Netzer to client use the JSON format. | ||
+ | Hence, it is easy to use a JSON parser within a browser to convert the message into a Javascript object. | ||
+ | |||
+ | The message is a JSON object type and contains one or more properties. | ||
+ | Each property represents an edge within the command tree. | ||
+ | The property key is the edge character. | ||
+ | Inner node edge values are also objects with one or more properties. | ||
+ | Leaf node edge values are simple data types like boolean or strings. | ||
+ | The addressed parameter specifies the type of those leaf values. | ||
+ | Numeric parameters are normally formated as strings. | ||