Updates on sensors.

docs/dev-guide.md

@@ -11,10 +11,10 @@ external Wi-Fi adapter if Wi-Fi functionality is desired. The practicality of
 compiling Python on the first generation of Raspberry Pis is also very
 questionable.
 
-Sensors required for operation are (links are breakout board shops):
-+ [__AS7265x__](https://www.tindie.com/products/onehorse/compact-as7265x-spectrometer/)
-+ [__VEML6075__](https://www.sparkfun.com/products/15089)
-+ [__APDS-9301__](https://www.sparkfun.com/products/14350)
+Sensors required for operation are:
++ AS7265x
++ VEML6075
++ APDS-9301
 
 They provide the spectrometry data, UV data and illuminance data, respectively.
 They all support I2C, AS7265x supports UART in addition.
@@ -25,3 +25,66 @@ the Raspberry's USB port. This also allows for considerable versatility, as it
 enables the resulting device to be either wall-powered or battery-powered.
 In a portable configuration, I used a one-cell power bank, which allowed for
 about 45 minutes of continuous operation.
+
+## AS7265x chipset
+_[Datasheet][1ds] [Buy breakout board][1]_
+
+This chipset supports either I2C or UART. Because transferring large amounts of
+data over I2C is rather cumbersome, TeraHz uses AS7265x in UART mode.
+
+This chipset consists of three rather small surface-mounted chips and requires
+an EEPROM. To lower the complexity of assembly for the end-user, I recommend
+using a breakout board.
+
+The serial UART connection operates at 115200 baud, which seems to be the
+standard for most recent embedded peripherals. As with most serial hardware,
+the TxD and RxD lines must be crossed over when connecting to the processor.
+
+Communication with the sensor is simple and clear through AT commands. There's
+a lot of them, all documented inside the datasheet, but the most important one
+is `ATGETCDATA`, which returns the calibrated spectral data from the sensors.
+
+The data is returned in the form of a comma-separated list of floating point
+values, ending with a newline. The order is alphabetical, which is __different
+from wavelength order__. See the datasheet for more information.
+
+## VEML6075
+
+This chip communicates through I2C and provides TeraHz with UVA and UVB
+irradiance readings. It's not an ideal chip for this task, as it's been marked
+End-of-Life by Vishay and it'll have to be replaced with a better one in future
+hardware versions of TeraHz.
+
+The chip resides at the I2C address `0x10`. There's not a lot of communication
+required: at initialization, the integration time has to be set and after that,
+the sensor is ready to go.
+
+16-bit UV values lie in two two-byte registers, `0x07` for UVA and `0x09` for
+UVB. For correct result conversion, there are also two correction registers,
+UVCOMP_1 and 2, located at `0x0A` and `0x0B`, respectively.
+
+To convert these four values into irradiances, they must be multiplied by
+certain constants, somewhat loosely defined in the sensor datasheet. Keep in
+mind that the way of computing the "irradiance" is very much experimentally
+derived, and even Vishay's tech support doesn't know how exactly to calculate
+the irradiance.
+
+## APDS-9301
+
+This chip measures illuminance in luxes and like the VEML6075, connects through
+I2C. Unlike the VEML6075, this chip is very good at its job, providing accurate
+and fast results without undefined mathematics or required calibration.
+
+At power-on, it needs to be enabled and the sensor gain set to the high setting,
+as the formula for Lux calculation is only defined for that setting. This
+initialization is handled by the sensors module.
+
+The lux reading is derived from two channels, descriptively called CH0 and CH1,
+residing in respective 16-bit registers at addresses `0xAC` and `0xAE`.
+
+
+
+[1]: https://www.tindie.com/products/onehorse/compact-as7265x-spectrometer/
+[2]: https://www.sparkfun.com/products/15089
+[3]: https://www.sparkfun.com/products/14350
+[1ds]: sensor-docs/AS7265x.pdf