Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
en:netzer:commandinterface [2013/06/04 21:43]
127.0.0.1 external edit 		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.
  

Trace:

QR Code
QR Code Command interface (generated for current page)