# HG changeset patch
# User Tero Marttila <terom@paivola.fi>
# Date 1415461876 -7200
# Node ID b1f2b34d4f8ca5e722bea3647537ddd6d71bee90
# Parent  e743c905cbf5884782b48d63a796f6114f3e4542
README: docdoc serial commands

diff -r e743c905cbf5 -r b1f2b34d4f8c README.md
--- a/README.md	Sat Nov 08 17:51:09 2014 +0200
+++ b/README.md	Sat Nov 08 17:51:16 2014 +0200
@@ -12,3 +12,64 @@
     # /dev/arduino
     SUBSYSTEMS=="usb", ATTRS{product}=="FT232R USB UART", ATTRS{idProduct}=="6001", ATTRS{idVendor}=="0403", SYMLINK+="arduino arduino_$attr{serial}"
 
+## Protocol
+
+The protocol used is ASCII with decimal.
+Commands are given as a command character, followed by command-specific arguments, and terminated by a newline character.
+The implementation supports up to 8 arguments.
+
+### Syntax (EBNF)
+
+    dmx-command:
+
+        cmd { sep arg  } eol
+
+    cmd:
+        'a'..'z' | 'A'..'Z'
+
+    arg:
+        '0'..'9' [ arg ]
+
+    sep:
+        '\t' | ' ' | ','
+
+    eol:
+        '\r' | '\n'
+
+### Commands
+
+The output state keeps track of both channel values, as well as the number of active channels. Only the channels up to
+the highest active channel are output. Up to 255 channels are supported.
+
+All commands ensure that any modified channels will become active.
+
+#### *c*lear
+
+    c
+
+Reset to initial state, with all channels inactive.
+
+#### *o*ut
+    o <value0> ... <valueN>
+
+Set active channels 0..N to given $value0..$valueN. All remaining channels will be marked inactive.
+
+#### *f*ill
+    f <start> <end> <value0> ... <valueN>
+
+Set channel $start+0 = $value0, ... $start+N = $valueN, up to $end, repeating $value0..N as needed.
+
+#### *r*ange
+    r <start> <stop> <step> <value>
+
+Set channels $start, $start + $step, ..., $end (inclusive) to the given $value.
+
+#### *s*et
+    s <start> <value0> ... <valueN>
+
+Set channels start..start+N to the given $value0..$valueN. Ensures channels up to N are valid.
+
+#### *z*ero
+    z [<count>]
+
+Set channels 1..$count to zero, and null all following channels.