From 8f27c02cad3ee91fcaa3a7df4d25805a287f820c Mon Sep 17 00:00:00 2001 From: David Runge Date: Sun, 23 Apr 2017 19:09:41 +0200 Subject: README.rst: Switching to ReStructuredText. Adding build instructions. Fixing all links to local repository, ignoring github links. --- README.rst | 246 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 README.rst (limited to 'README.rst') 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 + + random241.scd + +.. |read_gpio.py| raw:: html + + read_gpio.py + +.. |random241.py| raw:: html + + random241.py + +.. |supercollider| raw:: html + + SuperCollider + +.. |adafruit_bbio| raw:: html + + AdaFruit_BBIO + +.. |americium241| raw:: html + + Americium 241 + +.. |americium241-ionization_detectors| raw:: html + + ionization smoke detectors + +.. |github-gabriel_zoeller| raw:: html + + Gabriel Zöller + +.. |sugru| raw:: html + + Sugru + + + -- cgit v1.2.3-54-g00ecf