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

12 files changed, 246 insertions, 179 deletions

diff --git a/README.md b/README.md
deleted file mode 100644
index 3c08dbc..0000000
--- a/README.md
+++ /dev/null
@@ -1,54 +0,0 @@
-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](https://raw2.github.com/davezerave/random241/master/SuperCollider/random241.scd) script that can interface with it and a rudimental python script [read_gpio.py](https://raw2.github.com/davezerave/random241/master/remote_control/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_harvester](https://github.com/davezerave/random241/tree/master/entropy_harvester) you'll need the following packages and dependencies installed (names may vary depending on your distribution!):
-- python2
-- python2-numpy
-- python2-pyliblo
-- opencv
-- liblo
-
-For the [SuperCollider](https://github.com/davezerave/random241/tree/master/SuperCollider) script you'll need [SuperCollider](http://supercollider.github.io/) installed (duh!).
-
-For the [remote_control](https://github.com/davezerave/random241/tree/master/remote_control) you'll need the following:
-- python2
-- python2-pyliblo
-- [AdaFruit_BBIO](https://github.com/adafruit/adafruit-beaglebone-io-python)
-- liblo
-
-If you want to build your own random number generator from scratch, you can follow my little [howto guide](https://github.com/davezerave/random241/tree/master/howto) (it's far from being perfect though).
-
-Features:
------
-
-As this is an ongoing project and was executed primarily within the boundaries of my course work for [Audiovisual Programming - Embedded Systems](https://github.com/redFrik/udk10-Embedded_Systems) led by Fredrik Olofsson at UDK Berlin in 2013/ 2014, bugs can be expected (especially if you set up your own device!) and the reporting of those is very welcome!
-For an audio example, check out my [1)3\/1532 Bandcamp](https://deviser.bandcamp.com/album/no-place-like-dev-random-random241).
-
-Currently the list of features for the [entropy_harvester](https://github.com/davezerave/random241/tree/master/entropy_harvester) is as follows:
-- 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
-
-The [SuperCollider](https://github.com/davezerave/random241/tree/master/SuperCollider) script is able to:
-- 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.
-
-The [remote_control](https://github.com/davezerave/random241/tree/master/remote_control) script is able to:
-- Read GPIO data from BeagleBone Black (P9_39-42 for now)
-- Send sensor data as OSC message to predefined host and port
-
-TODOs:
-------
-- Externalization of settings for [remote_control](https://github.com/davezerave/random241/tree/master/remote_control) and [entropy_harvester](https://github.com/davezerave/random241/tree/master/entropy_harvester)
-- Further settings and advancements in sound for the SuperCollider script
-- Performance enhancements for entropy_harvester using different search algorithm (maybe even switch to C++)
-- Detection of false positives (pixel errors) on wacky cameras
-
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>
+
+
+
diff --git a/entropy_harvester/random241.log b/entropy_harvester/random241.log
deleted file mode 100644
index 77d2dbf..0000000
--- a/entropy_harvester/random241.log
+++ /dev/null
@@ -1,57 +0,0 @@
-2014-02-14 20:58:59,399 Grabbing random numbers from: 640x480px.
-2014-02-14 20:59:02,192 Balancing between one cluster.
-2014-02-14 20:59:02,192 318.563838772, 366.493476925
-2014-02-14 20:59:02,192 318.563838772, 366.493476925 (balance mean)
-2014-02-14 20:59:02,192 0.497755998081, 0.763528076927 (float)
-2014-02-14 20:59:06,866 Balancing between one cluster.
-2014-02-14 20:59:06,867 158.489023222, 122.496073032
-2014-02-14 20:59:06,867 238.526430997, 244.494774979 (balance mean)
-2014-02-14 20:59:06,867 0.247639098784, 0.25520015215 (float)
-2014-02-14 20:59:21,288 Balancing between one cluster.
-2014-02-14 20:59:21,288 244.447148175, 206.511969209
-2014-02-14 20:59:21,288 240.50000339, 231.833839722 (balance mean)
-2014-02-14 20:59:21,288 0.381948669024, 0.430233269186 (float)
-2014-02-14 20:59:45,095 Balancing between one cluster.
-2014-02-14 20:59:45,095 540.879599909, 363.808486106
-2014-02-14 20:59:45,095 315.59490252, 264.827501318 (balance mean)
-2014-02-14 20:59:45,096 0.845124374858, 0.757934346054 (float)
-2014-02-14 20:59:55,247 Balancing between a couple of clusters.
-2014-02-14 20:59:55,247 140.694326683, 174.408694235
-2014-02-14 20:59:55,247 280.614787352, 246.743739902 (balance mean)
-2014-02-14 20:59:55,247 0.219834885442, 0.363351446324 (float)
-2014-02-14 21:00:03,442 Balancing between one cluster.
-2014-02-14 21:00:03,443 248.094510127, 201.955945268
-2014-02-14 21:00:03,443 275.194741148, 239.279107463 (balance mean)
-2014-02-14 21:00:03,443 0.387647672073, 0.420741552643 (float)
-2014-02-14 21:00:18,271 Balancing between one cluster.
-2014-02-14 21:00:18,271 330.475657259, 78.4864409544
-2014-02-14 21:00:18,271 283.092014878, 216.308726533 (balance mean)
-2014-02-14 21:00:18,272 0.516368214467, 0.163513418655 (float)
-2014-02-14 21:00:36,249 Balancing between one cluster.
-2014-02-14 21:00:36,249 256.406174297, 476.751619252
-2014-02-14 21:00:36,250 279.756284806, 248.864088123 (balance mean)
-2014-02-14 21:00:36,250 0.40063464734, 0.993232540108 (float)
-2014-02-14 21:00:44,464 Balancing between one cluster.
-2014-02-14 21:00:44,464 244.477272727, 0.0
-2014-02-14 21:00:44,464 275.836394575, 221.212522776 (balance mean)
-2014-02-14 21:00:44,464 0.381995738636, 0.0 (float)
-2014-02-14 21:00:54,979 Balancing between one cluster.
-2014-02-14 21:00:54,979 422.452380952, 202.0
-2014-02-14 21:00:54,979 290.497993212, 219.291270498 (balance mean)
-2014-02-14 21:00:54,979 0.660081845238, 0.420833333333 (float)
-2014-02-14 21:01:43,662 Balancing between one cluster.
-2014-02-14 21:01:43,662 159.037931016, 168.087604319
-2014-02-14 21:01:43,662 278.547078467, 214.636391755 (balance mean)
-2014-02-14 21:01:43,662 0.248496767212, 0.350182508998 (float)
-2014-02-14 21:02:33,203 Balancing between one cluster.
-2014-02-14 21:02:33,203 430.690957968, 383.019316744
-2014-02-14 21:02:33,203 291.225735092, 228.66830217 (balance mean)
-2014-02-14 21:02:33,203 0.672954621825, 0.797956909884 (float)
-2014-02-14 21:02:37,488 Balancing between one cluster.
-2014-02-14 21:02:37,488 490.821583091, 193.855915219
-2014-02-14 21:02:37,488 306.579261861, 225.990426251 (balance mean)
-2014-02-14 21:02:37,488 0.76690872358, 0.403866490039 (float)
-2014-02-14 21:02:59,852 Balancing between one cluster.
-2014-02-14 21:02:59,852 416.487631031, 223.0
-2014-02-14 21:02:59,853 314.429859659, 225.776824376 (balance mean)
-2014-02-14 21:02:59,853 0.650761923487, 0.464583333333 (float)
diff --git a/howto/README.md b/howto/README.md
deleted file mode 100644
index cadc64c..0000000
--- a/howto/README.md
+++ /dev/null
@@ -1,68 +0,0 @@
-HOWTO build an Americium 241 driven random number generator
-===========================================================
-
-As a showcase I'll demonstrate the creation of my device below.
-You'll need a couple of things to build an Americium 241 driven random number generator (RNG). Read through **all of this** before starting!
-
-###First things first though
-
-**[Americium 241](http://en.wikipedia.org/wiki/Americium) 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 due to mal-handling of Americium 241!
-Don't be a fool, work responsibly!
-
-###Materials
-
-####Americium 241
-If you're living in the Americas, you'll most likely still have [ionization smoke detectors](http://en.wikipedia.org/wiki/Americium#Ionization_detectors) around. For (mostly) everyone else, there's the possibility of ordering Americium on ebay!
-As I live in Germany I opted for the second option (ionization detectors are not used in private households anymore). My sample came in a nice and useful shape:
-![Americium 241 sample, ordered on ebay](https://raw2.github.com/davezerave/random241/master/howto/IMG_6536.JPG)
-
-It's a small sample of 4mm diameter in a steel casing.
-
-####Webcam
-You can basically 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 [Gabriel Zöller](https://github.com/fahrstuhl) wanted to get rid of his and it was broken in just a beautiful and fitting way (with the lens already removed):
-![Gsmart Mini 3](https://raw2.github.com/davezerave/random241/master/howto/IMG_6537.JPG)
-
-
-####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:
-![19" rack server power supply](https://raw2.github.com/davezerave/random241/master/howto/IMG_6761.JPG)
-
-
-###Building the RNG
-It is highly recommended to use nippers when handling the Americium 241 sample:
-![Americium 241 sample on steel](https://raw2.github.com/davezerave/random241/master/howto/IMG_6543.JPG)
-
-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 (as you can see in the picture below).
-![Americium 241 sample with curb](https://raw2.github.com/davezerave/random241/master/howto/IMG_6547.JPG)
-
-Now the sample was put on top of the lens mount with the Americium pointing directly at the chip.
-![Americium 241 sample over webcam sensor chip](https://raw2.github.com/davezerave/random241/master/howto/IMG_6549.JPG)
-
-You might have to improvise a little - depending on your hardware - to make things work. [Sugru](http://sugru.com/about/) was my friend, fixing the sample over the camera chip. I know, it looks ugly, but it certainly gets the job done!
-![Americium 241 sample covered with Sugru, fixed over webcam sensor chip](https://raw2.github.com/davezerave/random241/master/howto/IMG_6550.JPG)
-
-**Note of advice**
-Unfortunately (for me), the Gsmart Mini 3 is not a webcam, but 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!
-
-After that was done, I was able to place the camera in the above mentioned casing, while leading the USB and push button switch cable out.
-![Americium 241 sample on camera in open casing](https://raw2.github.com/davezerave/random241/master/howto/IMG_6757.JPG)
-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!
diff --git a/howto/IMG_6757.JPG b/images/camera_in_casing.jpg
index 51a6e92..51a6e92 100644
--- a/howto/IMG_6757.JPG
+++ b/images/camera_in_casing.jpg
diff --git a/howto/IMG_6761.JPG b/images/casing.jpg
index c50df17..c50df17 100644
--- a/howto/IMG_6761.JPG
+++ b/images/casing.jpg
diff --git a/howto/IMG_6537.JPG b/images/gsmart_mini3.jpg
index 4a0711c..4a0711c 100644
--- a/howto/IMG_6537.JPG
+++ b/images/gsmart_mini3.jpg
diff --git a/howto/IMG_6536.JPG b/images/sample.jpg
index 3062210..3062210 100644
--- a/howto/IMG_6536.JPG
+++ b/images/sample.jpg
diff --git a/howto/IMG_6550.JPG b/images/sample_fixed_over_chip.jpg
index a041330..a041330 100644
--- a/howto/IMG_6550.JPG
+++ b/images/sample_fixed_over_chip.jpg
diff --git a/howto/IMG_6543.JPG b/images/sample_on_steel.jpg
index c317ad3..c317ad3 100644
--- a/howto/IMG_6543.JPG
+++ b/images/sample_on_steel.jpg
diff --git a/howto/IMG_6549.JPG b/images/sample_over_chip.jpg
index 6762885..6762885 100644
--- a/howto/IMG_6549.JPG
+++ b/images/sample_over_chip.jpg
diff --git a/howto/IMG_6547.JPG b/images/sample_with_curb.jpg
index 487496d..487496d 100644
--- a/howto/IMG_6547.JPG
+++ b/images/sample_with_curb.jpg