small doc updates

commandline/blink1-lib.c

@@ -545,7 +545,8 @@ int blink1_writePatternLine(hid_device *dev, uint16_t fadeMillis,
     g = (blink1_enable_degamma) ? blink1_degamma(g) : g ;
     b = (blink1_enable_degamma) ? blink1_degamma(b) : b ;
 
-    uint8_t buf[blink1_buf_size] = {blink1_report_id, 'P', r,g,b, (dms>>8), (dms % 0xff), pos };
+    uint8_t buf[blink1_buf_size] = 
+        {blink1_report_id, 'P', r,g,b, (dms>>8), (dms % 0xff), pos };
     int rc = blink1_write(dev, buf, sizeof(buf) );
     return rc;
 }
@@ -577,8 +578,8 @@ int blink1_savePattern( hid_device *dev )
 
     buf[0] = blink1_report_id;     // report id
     buf[1] = 'W';   // command code for "write pattern to flash"
-    buf[2] = 0x55;
-    buf[3] = 0xAA;
+    buf[2] = 0xBE;
+    buf[3] = 0xEF;
     buf[4] = 0xCA;
     buf[5] = 0xFE;
     buf[6] = 0x00;

docs/blink1-hid-commands.md

@@ -3,7 +3,8 @@ blink(1) HID commands
 =====================
 
 Communication with blink(1) is done via USB HID Feature Reports.
-This document shows the format of the data packet sent to blink(1).
+blink(1) currently responds to one feature report, with a report id of 0x01.
+This document shows the formats of the feature report data packet sent to blink(1).
 
 
 ## Command Summary ##
@@ -32,7 +33,7 @@ where:
        tl = (fadetimeMillis/10) & 0xff
        on = 1 or 0, indicating on/off, play/pause, etc.
        st = 1 or 0, indicating on/off, maintain state or clear state (mk2 only)
-        p = position in list, starts at 0, goes to patt_max-1 (patt_max=12(mk1),16(mk2))
+        p = position in list, starts at 0, goes to patt_max-1 
        sp = start loop position (0 - patt_max-1)
        ep = end loop position (1 - patt_max)
        ad = address starting at 1
@@ -47,7 +48,8 @@ where:
 Protocol
 --------
 
-blink(1) takes 8 bytes of input
+The blink(1) feature report packet is 8 bytes long.
+The structure of that packet is roughly:
 
     - byte 0 = report_id (0x01)
     - byte 1 = command action ('c' = fade to rgb, 'v' get firmware version, etc.)
@@ -58,13 +60,14 @@ blink(1) takes 8 bytes of input
     - byte 6 = cmd arg 4 (e.g. tl)
     - byte 7 = cmd arg 5 (e.g. ledn)
 
-Some things to note:
+Note:
 
 - The command action is the ascii value of the letter given (e.g. 'c' = 0x63)
 - Any command with unused cmd args should set them to zero.
 - On mk2 devices, gamma-correction of R,G,B values is done on the device,
   while on mk1 devices, the gamma correction is done in blink1-lib
-
+- The preferred implementation of of the protocol is in blink1-lib.{c,h}
+- patt_max = 12 (mk1), patt_max = 32 (mk2)
 
 The most common command is "fade to RGB", which has the form:
 
@@ -77,16 +80,23 @@ The most common command is "fade to RGB", which has the form:
     - byte 6 = tl    (fadeMillis/10 low byte)
     - byte 7 = 0     (unused on mk1, 0=all on mk2) 
 
-(th: time/cs high (T >>8)  where time 'T' is a number of 10msec ticks
-tl : time/cs low (T & 0xff)
-
 
 Commands
 --------
 
 ### Fade To RGB - `format: {0x01, 'c', r,g,b,    th,tl, 0 }`
 
-This command does not produce a return value
+This is the most common command sent to a blink(1).
+It lights up the blink(1) with the specified RGB color,
+fading to that color over a specified number of milliseconds.
+
+For a given fade time "fadeMillis", the "th" and "tl" values are computed by:
+    th = (fadetimeMillis/10) >> 8
+    tl = (fadetimeMillis/10) & 0xff
+
+The R,G,B, values are the 0-255 R,G,B components of the color to send.
+
+This command does not produce a return value.
 
     - byte 0 = 0x01  (report_id)
     - byte 1 = 'c'   (command "fade to rgb")
@@ -99,7 +109,7 @@ This command does not produce a return value
 
 ### Servertickle - `format: {0x01, 'D', on,th,tl,  st,0, 0 }`
 
-This command does not produce a return value
+This command does not produce a return value.
 
     - byte 0 = 0x01  (report_id)
     - byte 1 = 'D'   (command "servertickle")

docs/blink1-mk2-tricks.md

@@ -147,13 +147,15 @@ Note that only the first 16 of 32 pattern lines are saved to flash.
 
 Is blink(1) playing a color pattern?
 ------------------------------------
+
     % blink1-tool --playstate
     playstate: playing:1 start-end:0-16 count:0 pos:4
 
 
 Start pattern playing, wait for it to stop
 ------------------------------------------
-    # play red & green part of default pattern 3 times
+
+# play red & green part of default pattern 3 times
     % blink1-tool --play 1,0,5,3
     # wait for "playing" to go to zero before continuing
     % while [ `blink1-tool --playstate | cut -c 20` != 0 ]