anchor.diff:  = Audience Participation
   Florian Jung
  -v0.0.7, 2015-04-06
  +v0.1.0, 2015-04-15
   :doctype: book
   :encoding: utf-8
   :lang: en
  
positive.code: 
  
  == Overview
  For my bachelor thesis I developed a Raspberry Pi-based system for Audience
  Participation in musical projects. I dubbed the core python software based on that
  title *paps* (*P* i-based *A* udience *P* articipation *S* ystem). However if you
  are not going to use a Raspberry Pi in your project, *paps* once more applies
  (*P* ython-based *A* udience *P* articipation *S* ystem). If you want to go even
  further and only use the interfaces and/or the network protocol for example, *paps*
  still works (*P* articipation  *S* ystem). +
  For a complete overview of the project see link:docs/project{outfilesuffix}[here]. +
  For some insights on how this came to be and how the individual parts evolved,
  have a look at the transcription of link:docs/notes{outfilesuffix}[my personal journal notes].
  
  This is the documentation of the core python code.
  
  
  
  === Goals
  The main goals for this project were:
  
  * Easy: The code should be easy to read and understand (Which was the basis for
    the decision to use python)
  * Extendibility: Clear and uniform interfaces to mix and extend components as needed
  * Speed: Naturally speed is important, so why python?
    - The first goal (it being easy was more important than it being fast)
    - Python is usually fast enough. In most cases it does quite well, especially
    after you have done some optimizing. Additionally there are several ways to improve
    speed even more, like using different interpreters (pypy,..) or taking advantage
    of the close relationship to c (cpython, writing your own c code,...). +
    Also, realtime processing/reaction would be nice, but is not a requirement.
  * Scalability: The system should not have to handle millions of people, relying
    on load-balancers, but it should work with anything from a handful to a hundred.
  
  
  
  
negative.code: 
  Requires an ACK-Packet to be sent.
  
  == Conclusion
  The well documented and commented source code allows results in good readability.
  Someone familiar with the general components of paps and/or this document, but new
  to the codebase itself should be able to understand the different parts quickly
  and start developing without any difficulties. This is further aided by the python
  programming language, which, except for a few peculiarities, allows for a straight
  forward way to write code. +
  The server autodiscovery of the audience participation protocol in combination with
  the ability to save runtime settings between executions (such as the device id) as
  demonstrated in GPIODetector make deployment even to a large number of sensors easy.
  Only a single SD card needs to be prepared where the software is set to automatically
  run at boot-time and the seats need to be allocated to the specific groups only once.
  Though the interface was the designed to run in a web browser so that it is possible
  to control the system from a variety of devices, including tablets, the sorting
  remains a tedious errand. It remains a demonstration implementation, showing one
  possible way of approaching this task and will mostly likely prove to work best
  only with few people. Identifying which physical sensor corresponds to a person
  in the interface has to be achieved by manually triggering the sensor. Of course
  this method does not scale well to an audience size of hundreds of people, but since
  it is only required to be done once, it might be considered an acceptable complication. +
  The uniform interfaces, especially `ChangeInterface` makes for a very modular implementation,
  allowing to freely combine different parts of the application (e.g. using a plugin
  with or without a CrowdController, placing a plugin directly on top of a sensor,
  etc.). Additionally the design of the APP enables the developer to easily connect
  to the included `SensorServer` from her own modules and even different programming
  languages. But it was designed with a certain environment and simplicity in mind.
  A closed off network only for APP devices, with no malicious clients and no or
  at least next to none other traffic. The result is a very naïve protocol with
  few or no control, authentication or security features built in. It is also very
  susceptible to tampering (intentional and unintentional) and potential denial of
  service attacks. That is adequate according to our predefined constraints, but should
  be kept in mind when actually deploying a system. +
  After some fine tuning the sensor performed remarkable well, even under more elaborate
  setups like placing a pillow on top of it. The Raspberry Pi was a good decision as
  an operating platform, both in price and in functionality. It provides more than
  enough computing power for this task and should be able to handle plugin execution
  as well. Nevertheless it might not be suited for this task in all situations. In
  tests I was only able to record a frequency of 200 to 240 update packets per second.
  The software itself has however proven to be capable of handling over 400 packets
  per second continuously. During these stress test over several (between 5 and 30)
  minutes I recorded hardly any packet loss, indicating APP's resilience might have
  been overengineering. Moreover this shows the sufficient speed of the system, although
  improvements could be easily achieved by benchmarking the current code, optimising
  slow sections or even implementing components in C. +
  Additionally to its versatility adheres the Pi with a price tag of 35$ to the goal
  of affordability. By connecting multiple sensors to a single computer further reduces
  the per seat price, making the force sensitive resistor at around 10€ the most expensive
  component. However research has shown that it is possible to construct a force sensor
  from everyday household items, likely reducing costs. Since the board to connect the
  Pi and sensors consists mostly of resistors, it should be constructable for little
  money too.
  
  With my work I was able to create an application, both in hardware as in software,
  letting audience members influence the execution of prerecorded music and change
  the volume and dominance of specific instruments. I further built a core framework
  for general audience participation, laying a foundation for different interaction
  methods. +
  This system moreover satisfies all set design goals within their constraints, including
  performance, construction cost, modularity and manageability.
  
  
  == How to
  