TSL256x: Added more Javadoc

driver-tsl256x/src/main/java/com/leinardi/android/things/driver/tsl256x/Tsl256x.java

@@ -49,24 +49,94 @@ public class Tsl256x implements Closeable {
     public static final float MAX_POWER_CONSUMPTION_UA = 600;
     private static final String TAG = Tsl256x.class.getSimpleName();
 
-    private static final int COMMAND_BIT = 0b1000_0000;        // Must be 1
-    private static final int CLEAR_BIT = 0b0100_0000;          // Clears any pending interrupt (write 1 to clear)
-    private static final int WORD_BIT = 0b0010_0000;           // 1 = read/write word (rather than byte)
-    private static final int BLOCK_BIT = 0b0001_0000;          // 1 = using block read/write
+    /**
+     * Select Command Register.
+     */
+    private static final int COMMAND_BIT = 0b1000_0000;
+    /**
+     * Interrupt clear. Clears any pending interrupt. This bit is a write-one-to-clear bit. It is
+     * self clearing.
+     */
+    private static final int CLEAR_BIT = 0b0100_0000;
+    /**
+     * SMB Write/Read Word Protocol. 1 indicates that this SMB transaction is using either
+     * the SMB Write Word or Read Word protocol.
+     */
+    private static final int WORD_BIT = 0b0010_0000;
+    /**
+     * Block Write/Read Protocol. 1 indicates that this transaction is using either the Block
+     * Write or the Block Read protocol.
+     */
+    private static final int BLOCK_BIT = 0b0001_0000;
 
-    private static final int REGISTER_CONTROL = 0x00;          // Control/power register
-    private static final int REGISTER_TIMING = 0x01;           // Set integration time register
+    /**
+     * The Control Register contains two bits and is primarily used to
+     * power the TSL256x device up and down.
+     */
+    private static final int REGISTER_CONTROL = 0x00;
+    /**
+     * The Timing Register controls both the integration time and the
+     * gain of the ADC channels. A common set of control bits is
+     * provided that controls both ADC channels. The Timing Register
+     * defaults to 02h at power on.
+     */
+    private static final int REGISTER_TIMING = 0x01;
+    /**
+     * The Interrupt Threshold registers store the values to be used as
+     * the high and low trigger points for the comparison function for
+     * interrupt generation. If the value generated by channel 0
+     * crosses below or is equal to the low threshold specified, an
+     * interrupt is asserted on the interrupt pin. If the value generated
+     * by channel 0 crosses above the high threshold specified, an
+     * interrupt is asserted on the interrupt pin. Registers
+     * THRESHLOWLOW and THRESHLOWHIGH provide the low byte
+     * and high byte, respectively, of the lower interrupt threshold.
+     * Registers THRESHHIGHLOW and THRESHHIGHHIGH provide the
+     * low and high bytes, respectively, of the upper interrupt
+     * threshold. The high and low bytes from each set of registers are
+     * combined to form a 16-bit threshold value. The interrupt
+     * threshold registers default to 00h on power up.
+     */
     private static final int REGISTER_THRESHHOLDL_LOW = 0x02;  // Interrupt low threshold low-byte
     private static final int REGISTER_THRESHHOLDL_HIGH = 0x03; // Interrupt low threshold high-byte
     private static final int REGISTER_THRESHHOLDH_LOW = 0x04;  // Interrupt high threshold low-byte
     private static final int REGISTER_THRESHHOLDH_HIGH = 0x05; // Interrupt high threshold high-byte
-    private static final int REGISTER_INTERRUPT = 0x06;        // Interrupt settings
+    /**
+     * The Interrupt Register controls the extensive interrupt
+     * capabilities of the TSL256x. The TSL256x permits both
+     * SMB-Alert style interrupts as well as traditional level-style
+     * interrupts. The interrupt persist bit field (PERSIST) provides
+     * control over when interrupts occur. A value of 0 causes an
+     * interrupt to occur after every integration cycle regardless of the
+     * threshold settings. A value of 1 results in an interrupt after one
+     * integration time period outside the threshold window. A value
+     * of N (where N is 2 through15) results in an interrupt only if the
+     * value remains outside the threshold window for N consecutive
+     * integration cycles. For example, if N is equal to 10 and the
+     * integration time is 402ms, then the total time is approximately
+     * 4 seconds.
+     */
+    private static final int REGISTER_INTERRUPT = 0x06;
     private static final int REGISTER_CRC = 0x08;              // Factory use only
-    private static final int REGISTER_ID = 0x0A;               // TSL2561 identification setting
-    private static final int REGISTER_CHAN0_LOW = 0x0C;        // Light data channel 0, low byte
-    private static final int REGISTER_CHAN0_HIGH = 0x0D;       // Light data channel 0, high byte
-    private static final int REGISTER_CHAN1_LOW = 0x0E;        // Light data channel 1, low byte
-    private static final int REGISTER_CHAN1_HIGH = 0x0F;       // Light data channel 1, high byte
+    /**
+     * The ID Register provides the value for both the part number and
+     * silicon revision number for that part number. It is a read-only
+     * register, whose value never changes.
+     */
+    private static final int REGISTER_ID = 0x0A;
+    /**
+     * The ADC channel data are expressed as 16-bit values spread
+     * across two registers. The ADC channel 0 data registers,
+     * DATA0LOW and DATA0HIGH provide the lower and upper bytes,
+     * respectively, of the ADC value of channel 0. Registers
+     * DATA1LOW and DATA1HIGH provide the lower and upper bytes,
+     * respectively, of the ADC value of channel 1. All channel data
+     * registers are read-only and default to 00h on power up.
+     */
+    private static final int REGISTER_DATA0_LOW = 0x0C;        // Light data channel 0, low byte
+    private static final int REGISTER_DATA0_HIGH = 0x0D;       // Light data channel 0, high byte
+    private static final int REGISTER_DATA1_LOW = 0x0E;        // Light data channel 1, low byte
+    private static final int REGISTER_DATA1_HIGH = 0x0F;       // Light data channel 1, high byte
 
     private static final int ID_PART_NUMBER = 0b1111_0000;
     private static final int ID_REVISION_NUMBER = 0b0000_1111;
@@ -173,6 +243,9 @@ public void close() throws IOException {
         }
     }
 
+    /**
+     * Gets the value for both the part number and silicon revision number for that part number.
+     */
     public byte getChipId() {
         return mChipId;
     }
@@ -289,8 +362,8 @@ public int[] readLuminosity() throws IOException {
 
     private int[] readLuminosityData() throws IOException {
         int[] luminosities = new int[3];
-        luminosities[0] = readRegWord(COMMAND_BIT | WORD_BIT | REGISTER_CHAN0_LOW) & 0xFFFF;
-        luminosities[1] = readRegWord(COMMAND_BIT | WORD_BIT | REGISTER_CHAN1_LOW) & 0xFFFF;
+        luminosities[0] = readRegWord(COMMAND_BIT | WORD_BIT | REGISTER_DATA0_LOW) & 0xFFFF;
+        luminosities[1] = readRegWord(COMMAND_BIT | WORD_BIT | REGISTER_DATA1_LOW) & 0xFFFF;
         luminosities[2] = luminosities[0] - luminosities[1];
         return luminosities;
     }