diff -r 67d97311077a -r d32454497beb doc/api
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/api	Wed Dec 24 23:45:16 2008 +0100
@@ -0,0 +1,58 @@
+What do we need?
+
+* outputs are addressed from 0..64
+* values for outputs are {"on", 1} or {"off", 0}
+    
+* set/clear single outputs (set_bit?)
+
+    # $state:	"on", "off", 0, 1
+    # $output:	0..63
+
+    set($state => $output, ...)
+    set($state => [$output, ...])
+
+    Examples
+
+    # setting single outputs
+    set(on => 0, off => 1, on => 2, off => 3, ....., off => 7);
+    set(on => [0, 2], off => [1, 3 .. 7]);
+
+    # alternate form of the above 
+    set(1 => 0, 0 => 1, 1 => 2, 0 => 3, ...., 0 => 7);
+    set(1 => [0, 2], on => [1, 3 ... 7]);
+
+
+    # explicitly switch on
+    on(0, 2);
+    # .. or off single values
+    off(1, 3 ... 7);
+
+* read a single output (get_bit?)
+
+    $result = get($output);
+    @result = get($output, ...);
+
+    Examples
+
+    $result = get(0);
+    @result = get(0 .. 7);
+	
+* setting several outputs in a row (set_block, write_block?)
+    
+    # $block: 0 .. 7
+    # $value: 8, 16, ... 64 bit integer
+
+    # setting several outputs in a row, $output has to be
+
+    write($value => $block);
+
+    Examples
+
+    write(0x05 => 0);
+    write(5 => 0);
+
+# get several outputs in a row (get_block, read_block?)
+
+    $result = read(0, 8);   # read 8 bit and return it as a number
+
+