Add documentation for Microcontroller (#603)

documentation.json

@@ -42,6 +42,7 @@
 	},
 	"Logic" : {
 		"Luacontroller" : "mesecons_luacontroller/doc/luacontroller",
+		"Microcontroller" : "mesecons_microcontroller/doc/microcontroler",
 		"FPGA" : "mesecons_fpga/doc/fpga",
 		"FPGA Programmer" : "mesecons_fpga/doc/programmer",
 		"Torch" : "mesecons_torch/doc/torch",

mesecons_microcontroller/doc/microcontroller/description.html

@@ -0,0 +1,64 @@
+<!-- Generate `description.html` from this by using `$ md2html -o description.html description.md`. -->
+<p>The Microcontroller is a semi-advanced programmable component with a persistent
+256 bit EEPROM memory.</p>
+<p>Warning: This device is largely considered deprecated and might contain bugs. It
+is recommended to use a Luacontroller instead.</p>
+<p>Detailed documentation can be found below:</p>
+<ul>
+<li>The Microcontroller's code is executed whenever any of the following events
+happens:<ul>
+<li>The Microcontroller is programmed. In this case the EEPROM and ports are all
+reset to <code>0</code> before.</li>
+<li>An incoming signal changes its state.</li>
+<li>An <code>after</code> event happens (see command <code>after</code> below).</li>
+</ul>
+</li>
+<li>There are 4 I/O ports (ABCD) and 256 EEPROM bits (1 to 256).</li>
+<li>The code consists of a sequence of commands.</li>
+<li>Everything after <code>:</code> is a comment.</li>
+<li>Strings are enclosed in <code>&quot;</code>s.</li>
+<li>Spaces and tabs outside of strings are ignored.</li>
+<li>Basic command syntax:<pre><code>    command_name`(`param1`,` param2`,` ...`)`
+</code></pre>
+</li>
+<li>Commands:<ul>
+<li><code>if(condition) commands [&gt; else_commands];</code>:
+Evaluates the given condition and takes the corresponding branch.
+The else branch is optional (as indicated by the <code>[</code> and <code>]</code>). The <code>&gt;</code> is part
+of the syntax and indicates the start of the else branch. The <code>;</code> marks the
+end of the if command.</li>
+<li><code>on(port1, port2, ...)</code>:
+Sets the given ports to <code>1</code>.</li>
+<li><code>off(port1, port2, ...)</code>:
+Sets the given ports to <code>0</code>.</li>
+<li><code>print(&quot;string&quot; or codition, ...)</code>:
+Evaluates the conditions and prints the concatenation of all params to stdout
+(only useful in singleplayer).</li>
+<li><code>after(time, &quot;more commands&quot;)</code>:
+Executes the commands in the string after the given time in seconds.
+There can only be one waiting <code>after</code> event at once.
+Warning: This is not reliable, ie. <code>minetest.after</code> is used.</li>
+<li><code>sbi(port_or_eeprom, condition)</code>:
+Evaluates the condition and sets the port or EEPROM bit to the resulting value.
+Note: EEPROM indices don't use <code>#</code> here, ie. it's <code>sbi(1, #2)</code>, not <code>sbi(#1, #2)</code>.</li>
+</ul>
+</li>
+<li>Conditions (sorted by descending precedence; they are all evaluated from left
+to right):<ul>
+<li><code>0</code>, <code>1</code>: constant</li>
+<li><code>A</code>, ..., <code>D</code>: value of a port. Takes writes that already happened during the
+current execution into account.</li>
+<li><code>#1</code>, ..., <code>#256</code>: value of an EEPROM bit. Takes writes that already happened
+during the current execution into account.</li>
+<li><code>!condition</code>: negation (can only be applied once, ie. not <code>!!1</code>)</li>
+<li><code>condition1 = condition2</code>: XNOR (equality)</li>
+<li><code>condition1 op condition2</code> where <code>op</code> is one of:<ul>
+<li><code>&amp;</code>: AND</li>
+<li><code>|</code>: OR</li>
+<li><code>~</code>: XOR (inequality)</li>
+</ul>
+</li>
+<li>Note: Explicit precedence using parentheses is not supported.</li>
+</ul>
+</li>
+</ul>

mesecons_microcontroller/doc/microcontroller/description.md

@@ -0,0 +1,59 @@
+<!-- Generate `description.html` from this by using `$ md2html -o description.html description.md`. -->
+
+The Microcontroller is a semi-advanced programmable component with a persistent
+256 bit EEPROM memory.
+
+Warning: This device is largely considered deprecated and might contain bugs. It
+is recommended to use a Luacontroller instead.
+
+Detailed documentation can be found below:
+
+* The Microcontroller's code is executed whenever any of the following events
+  happens:
+  * The Microcontroller is programmed. In this case the EEPROM and ports are all
+    reset to `0` before.
+  * An incoming signal changes its state.
+  * An `after` event happens (see command `after` below).
+* There are 4 I/O ports (ABCD) and 256 EEPROM bits (1 to 256).
+* The code consists of a sequence of commands.
+* Everything after `:` is a comment.
+* Strings are enclosed in `"`s.
+* Spaces and tabs outside of strings are ignored.
+* Basic command syntax:
+  ```
+      command_name`(`param1`,` param2`,` ...`)`
+  ```
+* Commands:
+  * `if(condition) commands [> else_commands];`:
+    Evaluates the given condition and takes the corresponding branch.
+    The else branch is optional (as indicated by the `[` and `]`). The `>` is part
+    of the syntax and indicates the start of the else branch. The `;` marks the
+    end of the if command.
+  * `on(port1, port2, ...)`:
+    Sets the given ports to `1`.
+  * `off(port1, port2, ...)`:
+    Sets the given ports to `0`.
+  * `print("string" or codition, ...)`:
+    Evaluates the conditions and prints the concatenation of all params to stdout
+    (only useful in singleplayer).
+  * `after(time, "more commands")`:
+    Executes the commands in the string after the given time in seconds.
+    There can only be one waiting `after` event at once.
+    Warning: This is not reliable, ie. `minetest.after` is used.
+  * `sbi(port_or_eeprom, condition)`:
+    Evaluates the condition and sets the port or EEPROM bit to the resulting value.
+    Note: EEPROM indices don't use `#` here, ie. it's `sbi(1, #2)`, not `sbi(#1, #2)`.
+* Conditions (sorted by descending precedence; they are all evaluated from left
+  to right):
+  * `0`, `1`: constant
+  * `A`, ..., `D`: value of a port. Takes writes that already happened during the
+    current execution into account.
+  * `#1`, ..., `#256`: value of an EEPROM bit. Takes writes that already happened
+    during the current execution into account.
+  * `!condition`: negation (can only be applied once, ie. not `!!1`)
+  * `condition1 = condition2`: XNOR (equality)
+  * `condition1 op condition2` where `op` is one of:
+    * `&`: AND
+    * `|`: OR
+    * `~`: XOR (inequality)
+  * Note: Explicit precedence using parentheses is not supported.

mesecons_microcontroller/init.lua

@@ -122,7 +122,7 @@ minetest.register_node(nodename, {
 		elseif fields.bnand then
 			fields.code = "sbi(C, !A|!B) :A and B are inputs, C is output"
 		elseif fields.btflop then
-			fields.code = "if(A)sbi(1,1);if(!A&#1)sbi(B,!B)sbi(1,0); if(C)off(B,1); :A is input, B is output (Q), C is reset, toggles with falling edge"
+			fields.code = "if(A)sbi(1,1);if(!A&#1)sbi(B,!B)sbi(1,0); if(C)off(B); :A is input, B is output (Q), C is reset, toggles with falling edge"
 		elseif fields.brsflop then
 			fields.code = "if(A)on(C);if(B)off(C); :A is S (Set), B is R (Reset), C is output (R dominates)"
 		end