91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
# TeraHz developer's guide
|
|
This document explains how TeraHz works. It's a good starting point for developers
|
|
and an interesting read for the curious.
|
|
|
|
# Hardware
|
|
TeraHz was developed on and for the Raspberry Pi 3 Model B+. Compatibility with
|
|
other Raspberries can probably be achieved by tweaking the device paths in the
|
|
`app.py` file, but isn't confirmed at this point. Theoretically, 3 Model B and
|
|
Zero W should work out of the box, but models without Wi-Fi will need an
|
|
external Wi-Fi adapter if Wi-Fi functionality is desired.
|
|
|
|
TeraHz depends on three separate sensor boards:
|
|
- AS7265x spectral chipset
|
|
- VEML6075 UV sensor
|
|
- APDS-9301 lux-meter
|
|
|
|
The sensors leech power from the GPIO connector, thus eliminating the need for a
|
|
separate power supply. The necessary power for the whole system is delivered through
|
|
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
|
|
_[Datasheet][2ds] [Buy breakout board][2]_
|
|
|
|
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
|
|
_[Datasheet][3ds] [Buy breakout board][3]_
|
|
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`. After a
|
|
successful read of both data registers, the lux value can be derived using the
|
|
formula in the sensor's datasheet.
|
|
|
|
|
|
|
|
[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
|
|
[2ds]: sensor-docs/veml6075.pdf
|
|
[3ds]: sensor-docs/APDS-9301.pdf
|