Illuminator_API.txt  Version 1.0 9/07

Written by Jonathan Foote (Head Rotor at rotorbrain.com) 
This supersedes the crippled API used on the playa (!)
 

The Iluminator board listens to the serial port for commands of the form

"<"-"L"-optionalAddress-commandChar-optIntData-">"

All commands are prefixed with <L and suffixed with > to indicate end of data.
There is no whitespace allowed inside a command. All characters are uppercase. 

optionalAddress is a 1-char integer between 0 and 9. If this is
specified, only boards with that address will respond. If not
specified, all boards will respond.

optIntData is unsigned short or unsigned char integer data in one or
more ascii characters. Not every command has data.

CommandChar is one of the following:


'F' -- smoothly fade from current color to target color
    over the duration specified by the 'T' command. 
    Example <L0F> -- execute fade on board at address zero. 


'A' -- set board address to N and save it in eeprom. 
    Example: <L1A5> Changes any boards at address 1 to address 5. 
    NOTE: At boot time, the board reads its address from eeprom. 
    This is undefined if the board has never seen an 'A' command.
    Use the address-less version of the command to ensure a new board
    has its address set correctly, e.g. <LA0> changes the address
    of all boards to 0. Make sure you don't overwrite other boards. 

The remaining commands take an integer argument N (but nothing will
happen until the fade command 'F' is called.)

'R' -- set target red value to N, 0 <= N <= 255
    Example: <LR64> -- set red target to 64 on all boards

'G' -- set target blue value to N. 0 <= N <= 255
    Example: <L2B255> -- set blue target to 255 on boards at address 2.

'B' -- set target green value to N. 0 <= N <= 255
    Example: <LG0> -- set green target to 0 on all boards

'T' -- set fade duration to N. N=180 is one second. N=0 is immediate (at the
    next fade command). 
    Example: <LT360> -- set program time to 2 second on all boards


Commands are cumulative: to turn all illuminators off immediately,
send a value of zero to all, then execute a fade with a zero time
value, in other words send the string "<LR0><LG0><LB0><LT0><LF>"

To fade between blue and red over one second, first set all blue immediate:
<LR0><LB255><LG0><LT0><LF>
Then send target color, time duration, then the fade command:
<LB0><LR255><LT180><LF>
(there's no need to set R because it hasn't changed.)



NEW COMMANDS IN VERSION 2:

HN - set hue to N. 0<=N<=360  0 = red, 120 = green, 240 = blue, 360 = red
VN - set value to N (0<=N<=255) Value of 0 is dark (black) value of 255 is max

example: to set cyan at half brightness: <LH180><LV127><LF>

H and V commands overwite any R, G, or B commands sent without a corresponding F command. R, G, B commands after a H or V command will overwrite that channel, so may not do what you expect. 

WN - Write current color to index N (0<=N<=15);
LN - Load index N color to current color (0<=N<=15);

Index colors are preset to:

0=white
1=red
2=green
3=blue
4=magenta
5=yellow
6=cyan
7=black (all off)

Repeats for 8-15. 

W and L commands are independent of F commands. You always need to issue a F command to actually display a color. But you can preload colors without displaying them by not issuing F commands between them. 

Example: to display cyan from color index 6: <LL6><LF>
Example: to write blue to index 5 without displaying it, <LR0><LG0><LB255><LW5>


KN - blink N times, at 5 hz. Blinks between index colors 0 and index color 1, so if you don't like white and red then load different colors with the W command.

C -- self-test Check. Blinks white the number of times corresponding to the address. Address 0 blinks white for a long period.