en:netzer:commandinterface

Differences

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

Link to this comparison view

Next revision		 Previous revision
en:netzer:commandinterface [2013/06/04 21:01] – created sveschen:netzer:commandinterface [2025/06/11 20:42] (current) – external edit 127.0.0.1
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.