removed old utils virtualenv

docs/build.md

@@ -0,0 +1,9 @@
+# TeraHz build guide
+In its early development phase, TeraHz was hard and time-consuming to compile and install.
+This is not case now, as the more optimized DietPi Linux distribution allows
+better performance and simpler configuration than formerly used Raspbian.
+
+## Downloading the preconfigured image
+DietPi needs some initial configuration to support TeraHz. To shorten the process,
+Preconfigured SD card images are available for download under the release tab in
+the Github repository

docs/dependencies.md

@@ -0,0 +1,26 @@
+# Development-stable dependencies
+The current development version of TeraHz has been verified to work with:
+
+  - Raspbian Stretch (9)
+  - Python 3.6.8 (built from source code and altinstall'd)
+  - Module versions (direct `pip3.6 list` output):
+
+```
+      Package         Version  
+      --------------- ---------
+      Click           7.0      
+      Flask           1.0.3    
+      itsdangerous    1.1.0    
+      Jinja2          2.10.1   
+      MarkupSafe      1.1.1    
+      numpy           1.16.4   
+      pandas          0.24.2   
+      pip             18.1     
+      pyserial        3.4      
+      python-dateutil 2.8.0    
+      pytz            2019.1   
+      setuptools      40.6.2   
+      six             1.12.0   
+      smbus           1.1.post2
+      Werkzeug        0.15.4   
+```

docs/dev-guide.md

@@ -0,0 +1,95 @@
+# 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. The practicality of
+compiling Python on the first generation of Raspberry Pis is also very
+questionable.
+
+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.
+
+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

docs/electrical.md

@@ -0,0 +1,55 @@
+# TeraHz Electrical Guide
+This section briefly explains the neccessary electrical connections between the
+Raspberry Pi and the sensors you'll need to make to ensure correct and safe
+operation.
+
+As mentioned before, TeraHz requires 3 sensors to operate. The simpler UVA/UVB
+sensor and the ambient light analyzer connect to the Raspberry's SMBus (I2C)
+bus, while the spectrometer connects via high-speed UART.
+
+![pinout](imgs/raspi-pinout.png)
+
+## PCBs vs breakout boards & jumpers
+The Raspberry Pi GPIO port includes enough power pins to require only jumper
+cables to connect the sensors to the Raspberry Pi. However, this is not a great
+idea. During development, jumper cables have repeatedly been proven to be an
+unreliable nuisance, and their absolute lack of rigidity helped me fry one of my
+development Raspberry Pis. For this reason, I wholeheartedly recommend using a
+simple PCB to route the connections from the Pi to the sensors. At this time,
+there is no official TeraHz PCB, but it shall be announced and included in the
+project when basic testing will be done.
+
+GPIO can be routed to the PCB with a standard old IDE disk cable, and terminated
+with another 40-pin connector at the PCB. Sensor breakouts should be mounted
+<<<<<<< HEAD
+through standard 0.1" connectors, male on the sensor breakout and female on the
+PCB. A shitty add-on header and a shitty add-on header v1.69bis can't hurt, either.
+=======
+through standard 0.1" connectors, male on the sensor brakout and female on the
+PCB. A shitty addon header and a shitty addon header v1.69bis can't hurt, either.
+>>>>>>> fd1f07d40dace3e003e49377d4771de53f8bdeb8
+
+## SMBus sensors
+SMBus is a well-defined version of the well-known I2C bus, widely used
+in computer motherboards for low-band bandwidth communication with various ICs,
+especially sensors and power-supply related devices. This bus is broken out on
+the Raspberry Pi GPIO port as the "I2C1" bus (see picture).
+
+Pins are familiarly marked as SDA and SCL, the same as with classic I2C. They
+connect to the SDA and SCL pins on the VEML6075 and APDS-9301 sensor.
+
+## UART sensor
+<<<<<<< HEAD
+Spectral sensor attaches through the UART port on the Raspberry pi (see picture).
+=======
+Spectrometry sensor attaches through the UART port on the Raspberry pi (see picture).
+>>>>>>> fd1f07d40dace3e003e49377d4771de53f8bdeb8
+
+The Tx and Rx lines must cross over, connecting the sensor's Tx line to the
+computer's Rx line and vice versa.
+
+## Power supply
+As the sensors require only a small amount of power, they can be powered directly from the Raspberry Pi itself, leeching power from the 3.3V lines.
+
+## Ground
+There's not a lot to say here, connect sensor GND to Pi's GND.

docs/index.md

@@ -0,0 +1,3 @@
+<img alt="TeraHz logo" src="imgs/logo-sq.png" width="200px">
+# TeraHz documentation - index
+This is the starting point of TeraHz documentation.