README.rst: Switching to ReStructuredText. Adding build instructions. Fixing all links to local repository, ignoring github links.

1 files changed, 246 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..c65be59
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,246 @@
+random241
+=========
+
+| Python scripts for harvesting entropy from a random number generator (with an
+ Americium 241 sample mounted over a webcam sensor as its source).
+
+| This repository also features an OSC enabled SuperCollider (|random241.scd|)
+  script that can interface with it and a rudimentary python script
+  (|read_gpio.py| - made for BeagleBone Black) that can be used to further
+  modify effects on the generated sounds in a live setup.
+
+Requirements:
+-------------
+
+For the entropy harvesting script (|random241.py|) you need the following
+packages and dependencies installed (names may vary depending on your
+distribution!):
+
+- python2
+- python2-numpy
+- python2-pyliblo
+- opencv
+- liblo
+
+For |random241.scd| you need |supercollider| installed.
+
+For the remote_control (|read_gpio.py|) you need the following:
+
+- python2
+- python2-pyliblo
+- |adafruit_bbio|
+- liblo
+
+Features:
+---------
+
+|random241.py|
+______________
+
+- Grabbing of bright areas (aka regions of interest in pixels) above a certain
+  threshold from a webcam
+- Calculation of mean x/y values from regions of interest and conversion to
+  float range
+- Sending of time, x and y values via OSC to predefined host and port
+
+|random241.scd|
+_______________
+
+- Receive OSC messages for the creation of SynthDefs with certain pitch,
+  amplitude, length and loop time, according to coordinates and time sent.
+- Receive OSC messages for manipulation of post processing SynthDefs (FreeVerb
+  for now).
+- Ignore OSC messages after a certain amount of SynthDefs created.
+- Release (all) SynthDefs after a certain amount of SynthDefs is reached.
+
+|read_gpio.py|
+______________
+
+- Read GPIO data from BeagleBone Black (P9_39-42 for now)
+- Send sensor data as OSC message to predefined host and port
+
+
+Build instructions
+------------------
+
+| As a showcase I'll demonstrate the creation of my device below.
+| You'll need a couple of things to build an |americium241| driven random number
+  generator (RNG). Read through **all of this** before starting!
+
+.. note::
+  |americium241| is NOT A TOY!
+  It's a transuranic radioactive chemical element. Respect working with it:
+
+  - Do not swallow it
+  - Don't wear it on your body
+  - Avoid touching it
+  - At best work in a safe environment (like a lab)
+  - Do not eat while working with it
+  - Keep in a closed steel or aluminium container, when not working with it
+
+  | This being said, **I am not** responsible for any harm inflicted on you
+    or your environment due to mal-handling of Americium 241!
+  | Don't be a fool, work responsibly!
+
+Materials
+_________
+
+Americium 241
++++++++++++++
+
+If you're living in the US, you might still have an
+|americium241-ionization_detectors| around. For (mostly) everyone else, there's
+the possibility of ordering Americium on ebay!
+
+.. figure:: https://git.sleepmap.de/audio/random241.git/plain/images/sample.jpg
+  :alt: Americium 241 sample
+
+  A small sample of Americium 241 (4mm diameter in a steel casing).
+
+Webcam
+++++++
+
+You can use any webcam for this project. There are some things to keep in mind
+though:
+
+- You will break it!
+- Don't use cameras below 2 megapixels (your resolution won't be of any use)
+- Make sure you'll be able to open it up and remove its lens!
+
+In my case a Mustek Gsmart Mini 3 has been used, because
+|github-gabriel_zoeller| wanted to get rid of his and it was broken in just a
+beautiful and fitting way (with the lens already removed):
+
+.. figure:: https://git.sleepmap.de/audio/random241.git/plain/images/gsmart_mini3.jpg
+  :alt: Gsmart Mini 3
+
+  Mustek Gsmart Mini 3 with lens removed.
+
+.. note::
+  | The Gsmart Mini 3 is not a webcam, although it can be used as one, if you
+    press a button on the backside of it, while connected via USB.
+  | As I don't want to open a box and press a button on a camera with an
+    Americium 241 sample in it, every time I want to use it, I had to solder a
+    push button switch to it.
+  | That turned out to be quite a messy job (because the button is very tiny
+    and so are its contacts on the board).
+  | If you end up with the same model of camera, do this first, before you
+    place the sample on top of the sensor chip!
+
+Casing
+++++++
+| Make sure you'll have a proper casing around for the sample to store in and
+  later for the camera and the sample to store (or build into for that matter).
+| I used a steel casing from an old 19" server rack power supply, that was
+  trashed at work:
+
+.. figure:: https://git.sleepmap.de/audio/random241.git/plain/images/casing.jpg
+  :alt: Casing
+
+  Casing sourced from old 19" rack server power supply.
+
+Building the RNG
+________________
+
+It is highly recommended to use nippers when handling the Americium 241 sample:
+
+.. figure:: \
+  https://git.sleepmap.de/audio/random241.git/plain/images/sample_on_steel.jpg
+  :alt: Americium 241 sample on steel
+
+  Americium 241 sample on steel.
+
+The lens mount has a certain diameter. To not have the sample fall on top of
+the camera chip, I drilled a hole into and cut out a piece of steel to be used
+as a curb for the sample.
+
+.. figure:: \
+  https://git.sleepmap.de/audio/random241.git/plain/images/sample_with_curb.jpg
+  :alt: Americium 241 sample with curb
+
+  Americium 241 sample with curb.
+
+Now the sample was put on top of the lens mount with the Americium pointing
+directly at the chip.
+
+.. figure:: \
+  https://git.sleepmap.de/audio/random241.git/plain/images/sample_over_chip.jpg
+  :alt: Americium 241 sample with curb over chip
+
+  Americium 241 sample with curb over chip.
+
+You might have to improvise a little - depending on your hardware - to make
+things work. |sugru| is your friend, fixing the sample over the camera chip. I
+know, it looks ugly, but it certainly gets the job done!
+
+.. figure:: \
+  https://git.sleepmap.de/audio/random241.git/plain/images/sample_fixed_over_chip.jpg
+  :alt: Americium 241 sample fixed over chip using sugru
+
+  Americium 241 sample fixed over chip using sugru.
+
+I was able to place the camera in the above mentioned casing, while leading the
+USB and push button switch cable out.
+
+.. figure:: \
+  https://git.sleepmap.de/audio/random241.git/plain/images/camera_in_casing.jpg
+  :alt: Camera in casing
+
+  Camera in casing.
+
+| As you can see here, I had to use two additional steel panels to complete the
+  casing in front and back of the box.
+| The box is made from steel panels all around otherwise, but had some open
+  spaces in front and back (for air circulation in its previous
+  use-case-scenario).
+| This device is now USB pluggable and on/off switchable!
+
+TODOs:
+------
+
+- Externalization of settings for |read_gpio.py| and |random241.py|
+- Further settings and advancements in sound for |random241.scd|
+- Performance enhancements for |random241.py| using different search algorithm
+  (maybe switch to C++?)
+- Detection of false positives (pixel errors) on wacky
+  cameras
+
+
+.. |random241.scd| raw:: html
+
+  <a href="https://git.sleepmap.de/audio/random241.git/tree/SuperCollider/random241.scd" target="_blank">random241.scd</a>
+
+.. |read_gpio.py| raw:: html
+
+  <a href="https://git.sleepmap.de/audio/random241.git/tree/remote_control/read_gpio.py" target="_blank">read_gpio.py</a>
+
+.. |random241.py| raw:: html
+
+  <a href="https://git.sleepmap.de/audio/random241.git/tree/entropy_harvester/random241.py" target="_blank">random241.py</a>
+
+.. |supercollider| raw:: html
+
+  <a href="https://supercollider.github.io" target="_blank">SuperCollider</a>
+
+.. |adafruit_bbio| raw:: html
+
+  <a href="https://github.com/adafruit/adafruit-beaglebone-io-python" target="_blank">AdaFruit_BBIO</a>
+
+.. |americium241| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Americium" target="_blank">Americium 241</a>
+
+.. |americium241-ionization_detectors| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Americium#Ionization_detectors" target="_blank">ionization smoke detectors</a>
+
+.. |github-gabriel_zoeller| raw:: html
+
+  <a href="https://github.com/fahrstuhl" target="_blank">Gabriel Zöller</a>
+
+.. |sugru| raw:: html
+
+  <a href="https://sugru.com" target="_blank">Sugru</a>
+
+
+