Merge branch 'master' into conner5

12 files changed, 563 insertions, 11 deletions

diff --git a/docs/Behaviors/Behavior.jpg b/docs/Behaviors/Behavior.jpg
new file mode 100644
index 0000000..c96ee84
--- /dev/null
+++ b/docs/Behaviors/Behavior.jpg
diff --git a/docs/Behaviors/Behaviors.pdf b/docs/Behaviors/Behaviors.pdf
new file mode 100644
index 0000000..32c5b75
--- /dev/null
+++ b/docs/Behaviors/Behaviors.pdf
diff --git a/docs/Behaviors/Behaviors.tex b/docs/Behaviors/Behaviors.tex
new file mode 100644
index 0000000..5105588
--- /dev/null
+++ b/docs/Behaviors/Behaviors.tex
@@ -0,0 +1,155 @@
+\documentclass{article}
+\usepackage{fullpage}
+\usepackage{graphicx}
+\begin{document}
+    \title{Behaviors: An Introduction and Exercises}
+    \author{Russell Cohen}
+    \date{\today}
+    \maketitle
+    \section{What is a behavior?}
+    At its most basic, a behavior is machine with two input terminals and two
+    output terminals.  One of these input terminals is external input.  The
+    other is feedback from the behavior.  Similarly, the behavior has two output
+    terminals.  One gets released externally as output, and the other gets fed
+    back to the behavior.  At their core, behaviors have nothing to do with
+    pixels are light effects -- this is merely how we commonly use them.
+    \begin{center}
+    \includegraphics[width=4 in]{Behavior.jpg}
+    \end{center}
+    \section{How do I write a behavior?}
+    At the core of a behavior is its \texttt{ProcessResponse} method which
+    tells a behavior what to get on input.  As you might expect, it has 2
+    input ports, and two output ports.  The `type' of inputs and outputs can be
+    anything -- numbers, strings, lists, however, in our system, the inputs
+    and outputs are all python dictionaries.  This allows us to have an
+    arbitrary number of named parameters.  As sample input might look
+    something like \texttt{{'Location':(20,20), 'Height':10}}.  When we
+    return a value, we return a tuple of \texttt{(list<dict>,list<dict>)}.  Note that on a
+    process response method you will actually be given a \textbf{List of
+        dictionaries} and you should iterate over them. 
+    \textbf{Important:} You should not directly modify the inputs!  Use
+    \texttt{dict(input)} to create a copy of them!
+    \section{Exercise 1: addFive}
+    Our goal: Create a behavior that will add 5 to the 'Value' field of the
+    input.  If no 'Value' field exists, we will set it to five.  Below is a
+    sample \verb processResponse  method to do this.  Note that process
+    response is the only part of a behavior that must be written (everything
+            else happens behind the scenes when you \textbf{inherit} from the
+            \texttt{Behavior} class.
+    \begin{verbatim}
+        def processResponse(self, inputs, recurrences):
+            output = [] #empty list 
+            for inp in inputs:
+                inpCopy = dict(inp)
+                if not ('Value' in inpCopy):
+                    inpCopy['Value'] = 0
+                inpCopy['Value'] += 5
+                output.append(inpCopy)
+            return (output, []) #empty list, no recurrences
+    \end{verbatim}
+    \section{Exercise 2: A Sum-er}
+        Create a behavior that outputs the sum of all previous input.  Hint:
+        You will need to use recurrences!
+    \section{Declaring and Configuring Behaviors}
+        Once you've written your behavior (or are using an already written
+            behavior, you will need to tell the light installation to use the
+            behavior.  This is done via XML in the configuration file.  When you
+            run the system, you specify a configuration file eg:
+            \texttt{python LightInstallation.py config/ConfigFile.xml}
+
+            Behaviors are specified in the \verb BehaviorConfiguration  section.
+            A sample behavior follows:
+           \begin{verbatim}
+            <Behavior>
+                <Class>behaviors.EchoBehavior</Class>
+                <Args>
+                    <Id>echo</Id>
+                    <RenderToScreen>False</RenderToScreen>
+                </Args>
+            </Behavior>
+            \end{verbatim}
+
+            The ``Class'' attribute specifies the \textbf{Python} class for this
+            behavior.  (The \verb behaviors.  prefix tells Python to look in the
+                behaviors folder).  You may recall that all classes SmootLight take a
+            single python dictionary as an argument -- this is embodied by the
+            \texttt{Args} tag.  A dictionary is created from the XML at runtime
+            -- this dictionary would be: \texttt{{'Id':'echo',
+                'RenderToScreen':False}}
+            The id we specify is the id that we can reference this behavior by
+            later.  The \verb RenderToScreen  attribute specifies whether or not
+            outputs from this behavior should be directed to the screen (some
+                    behaviors act only as the building blocks for other
+                    behaviors, and are never rendered directly to the screen)
+
+    \section{Behavior Chains}
+        I have mentioned several times that the system allows for behaviors to
+        be chained together to create many different effects -- often the
+        ``motion'' effect and the ``coloring'' effects are two separate
+        behaviors.  The result you see on the screen are these two pieces
+        connected together.  This allows us to build up many different behaviors
+        from a library of simple pieces.  Let's look at how we actually
+        accomplish this.
+        
+        Behavior Chaining is accomplished through the behavior chain class.
+        Here is an example of a behavior we declare (in XML) via a behavior
+        chain:
+        \begin{verbatim}
+        <Behavior>
+            <Class>behaviors.BehaviorChain</Class>
+            <Args>
+                <Id>runcolordecay</Id>
+                <Inputs>
+                    <Id>pygame</Id>
+                    <Id>randomLoc</Id>
+                </Inputs>
+                <ChainedBehaviors>
+                    <Id>colorchange</Id>
+                    <Id>running</Id>
+                    <Id>decay</Id>
+                </ChainedBehaviors>
+                <RecursiveHooks>{'running':'acceleratedie'}</RecursiveHooks>
+                <RenderToScreen>True</RenderToScreen>
+                <Mapper>gaussmap</Mapper>
+            </Args>
+        </Behavior>
+        \end{verbatim}
+
+        Note the importance of the `Id' field -- that is how we reference all
+        other components of the system.  Let's walk through what is going on
+        here.  We declare this behavior just like any other -- however, for
+        class, we specify \verb BehaviorChain .  The \verb Inputs  tag specifies
+        which inputs will be routed to this behavior.  In this case, it is
+        \verb pygame  and \verb randomLoc  , two previously declared behaviors.
+        Inputs from these behaviors will be passed to the behavior chain via
+        sensorInputs.  Next, we have the meet of this chain, the behaviors it is
+        composed of.  This states that first, an input is routed through
+        \texttt{colorchange}.  \verb colorchange adds a color field to the
+        sensor data.  Next, the input is routed to \verb running  a behavior
+        that makes pixels run back and forth.  Finally, the input is routed to
+        \verb decay  , a behavior that adds a decay ``PixelEvent'' that makes
+        individual pixels turn on and then decay.
+
+        The next item we see is \verb RecursiveHooks  .  This is a special
+        feature of the \verb BehaviorChain  that allows us to augment the
+        reccurences recursive events have.  We specify that we will augment the
+        recursive behavior of \verb running  with another behavior, 
+        \verb acceleratedie  which modifies increases the speed of the running
+        behavior, and stops the behavior after a certain number of iterations.
+        Note that recursive hooks take data in via their \textbf{external input}
+        port, and \textbf{not} their recursive port.
+        \begin{center} 
+        \includegraphics[width=4 in]{BehaviorwithRecursiveHook.jpg}
+        \end{center}
+        Finally, we state that this behavior will indeed be rendered directly to
+        the screen, by specifying:
+        \begin{center}\texttt{<RenderToScreen>True</RenderToScreen>} \end{center}
+        We also specify which PixelMapper we want to use (gaussmap):
+        \texttt{<Mapper>gaussmap</Map>}.  \verb gaussmap  is the id we assigned to the mapper when
+        we declared in the \verb PixelMappers  section of the xml.
+        \begin{center}
+        Phew.  This isn't as complicated as it sounds.  I promise.
+        \end{center}
+        Browse around the behaviors to get an idea of what is possible and what has been done.  They
+        all live in the behaviors folder.  Enjoy!
+        \end{document}
diff --git a/docs/Behaviors/BehaviorwithRecursiveHook.jpg b/docs/Behaviors/BehaviorwithRecursiveHook.jpg
new file mode 100644
index 0000000..84e99d6
--- /dev/null
+++ b/docs/Behaviors/BehaviorwithRecursiveHook.jpg
diff --git a/docs/ClassOverview.pdf b/docs/ClassOverview.pdf
new file mode 100644
index 0000000..530dfa6
--- /dev/null
+++ b/docs/ClassOverview.pdf
diff --git a/docs/XmlConfiguration.pdf b/docs/XmlConfiguration.pdf
new file mode 100644
index 0000000..9136232
--- /dev/null
+++ b/docs/XmlConfiguration.pdf
diff --git a/docs/XmlConfiguration.tex b/docs/XmlConfiguration.tex
new file mode 100644
index 0000000..6f45de2
--- /dev/null
+++ b/docs/XmlConfiguration.tex
@@ -0,0 +1,223 @@
+\documentclass{article}
+\usepackage{fullpage}
+\begin{document}
+    \title{XML in SmootLight: Configuration++}
+    \author{Russell Cohen}
+    \date{\today}
+    \maketitle
+    \section{Motivation}
+        Why use XML (or any non-code language for that matter) to configure code?  2 Reasons: 
+        \begin{itemize}
+            \item We would like small changes (like changing the color, speed, or type of behavior)
+            to be as quick as possible, and require modifying only 1 piece of code.
+            \item We would like these changes to be able to be made \emph{programmatically}
+            \item (Not applicable to python, but important in languages like Java or C): We want to
+            be able to make changes \textbf{without} having to recompile the source.
+        \end{itemize}
+        As you will see, however, XML in SmootLight goes beyond simple configuration.  XML in
+        SmootLight allows us to declare a LightSystem (an inherently non-declarative thing) in the
+        same way you might write a webpage in HTML.  We will refer to the XML system here-on-in as
+        `SmootConf'.  \textbf{The fastest way to get familiar with SmootConf is simply to look at
+        the XML files in the configuration file.  However, if you want a more structured approach to
+        its feature and subtleties this document should do the job.}  Without any further ado, lets start looking at
+        how this all works.
+    \section{Declaring a class in SmootConf}
+        The most common thing done is SmootConf is declaring a class -- Class declaration code will
+        get parsed by SmootLight at runtime and \emph{actually} \textbf{declare} your classes for
+        you, exactly how you describe them.  Classes are declared under a broader
+        \texttt{Configuration} tag which we will describe later.  Lets look at the declaration of
+        \texttt{PygameInput}, an input that takes data from a Pygame window.
+        \begin{verbatim}
+            <InputElement>
+                <Class>inputs.PygameInput</Class>
+                <Args>
+                    <Id>pygameclick</Id>
+                    <RefreshInterval>10</RefreshInterval>
+                    <Clicks>True</Clicks>
+                </Args>
+            </InputElement>
+        \end{verbatim}
+        The first attribute we see is the \texttt{Class} attribute.  This specifies what
+        fully-qualified Python class to this object should be an instance of.  In this case, it is
+        an instance of PygameInput, which lives in the inputs module/folder.  Next, we see the
+        \texttt{Args}.  The Args are where \emph{every} piece of configuration (except the actual
+        Class) goes.  Let me repeat that, becuase it is a common sticking point.  If you place
+        something in the configuration outside of the \texttt{Args} tag, it will not be read.
+        Period.
+
+        If you are familiar with the SmootLight system, you will know that many objects in
+        SmootLight behave like dictionaries -- you can use statements like
+        \texttt{Self['ParamName']} to access parameters.  If you have ever wondered where this
+        mystery dictionary is filled from, look no further -- it is here in the Args tag.  
+
+        Lets dig into the contents of the Arg tag.  First we see \texttt{Id}.  All components in the
+        SmootLight system are \emph{not} explicitly required to have an Id
+        specified.\footnote{Components declared without Id's will get a randomly assigned Id at
+        declaration time}
+        However, if you want to be able to reference this class in other places in the XML (which
+        we will look into later), you will need to specify and Id.  The other two parameters are
+        simply bits of configuration which will get passed to PygameInput when it gets instantiated.
+        
+    \section{The Structure of a SmootLight Configuration Document}
+        The individual class declarations are the `leaves' of a full configuration document that
+        gets interpreted by the parser.  In order for the parser to know what to do with them, it
+        also needs the branches.  The structure of these `branches' (tags) follow:
+        \begin{verbatim}
+            <LightInstallation>
+                <InstallationConfiguration>
+                    <Defaults />
+                </InstallationConfiguration>
+                <PixelConfiguration />
+                <PixelMapperConfiguration />
+                <RendererConfiguration />
+                <InputConfiguration />
+                <BehaviorConfiguration />
+            </LightInstallation>
+        \end{verbatim}
+        Under each of the tags indicated, place the classes that you want to instantiate in that
+        category.  Each category has a different child tag:
+        \begin{itemize}
+            \item PixelConfiguration: PixelStrip
+            \item PixelMapperConfiguration: PixelMapper
+            \item RendererConfiguration: Renderer
+            \item InputConfiguration: InputElement
+            \item BehaviorConfiguration: Behavior
+        \end{itemize}
+        Some further clarification on this: Recall in the previous section we inspected the
+        declaration of the Input element.  The input configuration for that system might have looked
+        like:
+        \begin{verbatim}
+            <InputConfiguration> 
+                <InputElement>
+                    <Class>inputs.PygameInput</Class>
+                    <Args>
+                        <Id>pygameclick</Id>
+                        <RefreshInterval>10</RefreshInterval>
+                        <Clicks>True</Clicks>
+                    </Args>
+                </InputElement>
+            </InputConfiguration>
+        \end{verbatim}
+        \texttt{InputElement}s live under the broader \texttt{InputConfiguration} tag.  Thats all in
+        terms of basic configuration -- all other features are going to be specific to the
+        particular class you are declaring (and the class should specify those).  However, the
+        system also offers a lot of features to give you more power and flexibility, as well as
+        minimizing repeated XML.
+    \section{XML Inheritance}
+        SmootConf allows you have XML objects inherit from this other.  Think of this as an
+        X:Include crossed with OO style inheritance, if those are familiar concepts.  The most basic
+        tag of inheritance in SmootConf is the \texttt{InheritsFrom} tag.  Here is a quick example
+        of it in action:
+        \begin{verbatim}
+            <Renderer Scale="4">
+                <InheritsFrom>renderers/Pygame.xml</InheritsFrom>
+            </Renderer>
+        \end{verbatim}
+        
+        And the contents of \texttt{renderers/Pygame.xml}:
+        \begin{verbatim}
+            <Renderer>
+                <Class>renderers.PygameRenderer</Class>
+                <Args>
+                    <Id>pygamerender</Id>
+                    <displaySize>(1300,50)</displaySize>
+                </Args>
+            </Renderer>
+        \end{verbatim}
+
+        The \texttt{InheritsFrom} tag indicates to look in the XML File indicated, parse it, and
+        recursively merge its tags with the siblings of the \texttt{InheritsFrom} tag.  From a high
+        level, the algorithm works as follows:
+
+        \begin{itemize}
+            \item For every tag:
+            \item If the tag is in the inheriter, use that.  Otherwise, use the inherited tag.  
+            \item Recurse to children.
+        \end{itemize}
+        
+        SmootConf adds a bit of syntactic sugar that allows you override args in the args dict when
+        doing inheritance by simply specifying them as attributes of the parent.  The example below
+        comes from a pixel layout config:
+        \begin{verbatim}
+            <PixelConfiguration>
+                <PixelStrip Id="strip1.1" originLocation="(0,0)" Reverse="True">
+                    <InheritsFrom>layouts/50PixelStrip.xml</InheritsFrom>
+                </PixelStrip>
+                <PixelStrip Id="strip1.2" originLocation="(200,0)">
+                    <InheritsFrom>layouts/50PixelStrip.xml</InheritsFrom>
+                </PixelStrip>
+        \end{verbatim}
+        
+        The contents of \texttt{layouts/50PixelStrip.xml} are:
+        \begin{verbatim}
+            <PixelStrip>
+                <Class>layouts.LineLayout</Class>
+                <Args>
+                    <pixelToPixelSpacing>4</pixelToPixelSpacing>
+                    <spacing>4</spacing> 
+                    <numPixels>50</numPixels>
+                </Args>
+            </PixelStrip>
+        \end{verbatim}
+
+        A careful reading of the algorithm will reveal some behaviors which are not specified.  What if there are
+        multiple instances of identical sibling tags?  The answer is that this is not currently
+        supported.  It may be supported in the future.
+        
+        If you want your tags to be added to an inherited config without trying to merge, put them
+        in an \texttt{APPEND} tag like so:
+
+        \begin{verbatim}
+            <Behaviors>
+                <InheritsFrom>behaviors/StockBehaviors.xml</InheritsFrom>
+                <APPEND>
+                    <Beavhior>
+                        <InheritsFrom>behaviors/SomethingElse.xml</InerhitsFrom>
+                    </Behavior>
+                    <Behavior>
+                        <Class>blah.blah</Class>
+                        <Args>
+                        </Args>
+                    </Behavior>
+                </APPEND>
+            </Behaviors>
+        \end{verbatim}
+    \section{Variable Bindings}
+        SmootConf allows developers to reference other variables within the \texttt{<Args>} tag.  These
+        references are dynamic, and are bound for the lifetime of the object and will updated as
+        their bound values update.  Here is an example:
+        \begin{verbatim}
+            <Behavior>
+                <Class>behaviors.SomeClass</Class>
+                <Args>
+                    <Id>dimming</Id>
+                    <DecayCoefficient>${DecayTime}$*5</DecayCoefficient>
+                    <DecayTime>10</DecayTime>
+                </Args>
+            </Behavior>
+        \end{verbatim}
+        In this (fake) example, we bind the DecayCoefficient to the value of DecayTime, which allows us to
+        set decay in a reasonable unit, decoupled from the coefficient required by the behavior
+        itself.
+
+        Under the hood, this feature is done with lambda functions.  When you query arguments on the
+        object, the lambda gets resolved (look at \texttt{operationscore/SmootCoreObject.py} for the
+        implementation of this).  Because of this, we also have to ability to go 1 layer deeper.  
+
+        Let's say you wanted to operate on another dictionary -- say, the current behavior packet or
+        and args of another behavior.  By surrounding your variable in quotes, querying its value
+        with product a lambda function, which, when given another dictionary, will resolve the
+        value.
+        \begin{verbatim}
+            <Behavior>
+                <Class>behaviors.SomeClass</Class>
+                <Args>
+                    <Id>stayinbounds</Id>
+                    <MaxX>100</MaxX>
+                    <OutOfBounds>'${x}$' &lt; ${MaxX}$</OutOfBounds>
+                </Args>
+            </Behavior>
+        \end{verbatim}
+        If you call \texttt{self['OutOfBounds']}, and pass it a dictionary with a value at key
+        \texttt{x}, it will return a boolean stating whether or not \texttt{x > MaxX}. 
+\end{document}
diff --git a/docs/designDocs.pdf b/docs/designDocs.pdf
deleted file mode 100644
index 78eb646..0000000
--- a/docs/designDocs.pdf
+++ /dev/null
diff --git a/docs/gettingStarted.pdf b/docs/gettingStarted.pdf
new file mode 100644
index 0000000..4d295f7
--- /dev/null
+++ b/docs/gettingStarted.pdf
diff --git a/docs/gettingStarted.tex b/docs/gettingStarted.tex
new file mode 100644
index 0000000..4d88ace
--- /dev/null
+++ b/docs/gettingStarted.tex
@@ -0,0 +1,37 @@
+\documentclass{article}
+\usepackage{fullpage}
+\usepackage{hyperref}
+\begin{document}
+    \title{150 Smoots Getting Started on Linux}
+    \author{Andrew Chen}
+    \date{\today}
+    \maketitle
+	\section{Repository Access}
+		\begin{itemize} 
+			\item \textbf{Install} Git packages with \texttt{sudo apt-get install git-core git-gui git-doc}. Set up your basic git settings \href{http://help.github.com/git-email-settings/}{like so}.
+			\item \textbf{Sign up} for a GitHub account (\href{https://github.com/signup/free}{here}) then ask Russell to add your account as a collaborator to the rcoh/SmootLight code repository.
+			\item \textbf{Connect} to the SmootLight GitHub code repository. Generate SSH keys and upload the public one to GitHub by following the instructions \href{http://help.github.com/linux-key-setup/}{here}.
+			\item \textbf{Clone and branch} the code repository; use \href{http://help.github.com/git-cheat-sheets/}{this cheatsheet} for help as necessary.
+		\end{itemize}
+	\section{Testing on Pygame}
+		\begin{itemize} 
+			\item \textbf{Install} Pygame with \texttt{sudo apt-get install python-pygame}.
+			\item \textbf{Setup} logging by running \texttt{./setup.sh}.
+			\item \textbf{Run} your LightInstallation code with \texttt{python LightInstallation.py}.
+		\end{itemize}
+	\section{Repository Check In}
+		\begin{itemize}
+			\item \textbf{Stage} files to be committed with \texttt{./ga}.
+			\item \textbf{Commit} your changes locally with \texttt{git commit}.
+			\item \textbf{Push} your changes to your branch with \texttt{git push origin yourbranchname}.
+			\item \textbf{Request a pull} to the source repository by following instructions \href{http://help.github.com/pull-requests/}{here}.
+			\item \textbf{Learn more} about working with remote repositories \href{http://help.github.com/remotes/}{here}.
+		\end{itemize}
+	\section{Latex Documentation}
+        \begin{itemize} 
+			\item \textbf{Install} Latex packages to be consistent with current documentation style. I had to run \texttt{sudo apt-get install texlive-fonts-recommended texlive-latex-extra} to successfully convert Russell's .tex to pdf.
+			\item \textbf{Edit} the .tex files with any text editor. I use vim for quick edits and gedit with the Latex plugin for autocompletion and quick previews. Get the Latex plugin with \texttt{sudo apt-get install gedit-latex-plugin}.
+            \item \textbf{Publish to PDF} with \texttt{pdflatex yourfile.tex}.
+			\item \textbf{View PDF} with \texttt{evince yourfile.pdf}.
+		\end{itemize}
+\end{document}
diff --git a/docs/tex/Behaviors.tex b/docs/tex/Behaviors.tex
new file mode 100644
index 0000000..9021581
--- /dev/null
+++ b/docs/tex/Behaviors.tex
@@ -0,0 +1,143 @@
+\documentclass{article}
+\usepackage{fullpage}
+\begin{document}
+    \title{Behaviors: An Introduction and Exercises}
+    \author{Russell Cohen}
+    \date{\today}
+    \maketitle
+    \section{What is a behavior?}
+    At its most basic, a behavior is machine with two input terminals and two
+    output terminals.  One of these input terminals is external input.  The
+    other is feedback from the behavior.  Similarly, the behavior has two output
+    terminals.  One gets released externally as output, and the other gets fed
+    back to the behavior.  At their core, behaviors have nothing to do with
+    pixels are light effects -- this is merely how we commonly use them.
+    \section{How do I write a behavior?}
+    At the core of a behavior is its \texttt{ProcessResponse} method which
+    tells a behavior what to get on input.  As you might expect, it has 2
+    input ports, and two output ports.  The `type' of inputs and outputs can be
+    anything -- numbers, strings, lists, however, in our system, the inputs
+    and outputs are all python dictionaries.  This allows us to have an
+    arbitrary number of named parameters.  As sample input might look
+    something like \texttt{{'Location':(20,20), 'Height':10}}.  When we
+    return a value, we return a tuple of (list<dict>,list<dict>).  Note that on a
+    process response method you will actually be given a \textbf{List of
+        dictionaries} and you should iterate over them. 
+    \textbf{Important:} You should not directly modify the inputs!  Use
+    \texttt{dict(input)} to create a copy of them!
+    \section{Exercise 1: addFive}
+    Our goal: Create a behavior that will add 5 to the 'Value' field of the
+    input.  If no 'Value' field exists, we will set it to five.  Below is a
+    sample \verb processResponse  method to do this.  Note that process
+    response is the only part of a behavior that must be written (everything
+            else happens behind the scenes when you \textbf{inherit} from the
+            \texttt{Behavior} class.
+    \begin{verbatim}
+        def processResponse(self, inputs, recurrences):
+            output = [] #empty list 
+            for inp in inputs:
+                inpCopy = dict(inp)
+                if not ('Value' in inpCopy):
+                    inpCopy['Value'] = 0
+                inpCopy['Value'] += 5
+                output.append(inpCopy)
+            return (output, []) #empty list, no recurrences
+    \end{verbatim}
+    \section{Exercise 2: A Sum-er}
+        Create a behavior that outputs the sum of all previous input.  Hint:
+        You will need to use recurrences!
+    \section{Declaring and Configuring Behaviors}
+        Once you've written your behavior (or are using an already written
+            behavior, you will need to tell the light installation to use the
+            behavior.  This is done via XML in the configuration file.  When you
+            run the system, you specify a configuration file eg:
+            \texttt{python LightInstallation.py config/ConfigFile.xml}
+
+            Behaviors are specified in the \verb BehaviorConfiguration  section.
+            A sample behavior follows:
+           \begin{verbatim}
+            <Behavior>
+                <Class>behaviors.EchoBehavior</Class>
+                <Args>
+                    <Id>echo</Id>
+                    <RenderToScreen>False</RenderToScreen>
+                </Args>
+            </Behavior>
+            \end{verbatim}
+
+            The ``Class'' attribute specifies the \textbf{Python} class for this
+            behavior.  (The \verb behaviors.  prefix tells Python to look in the
+                behaviors folder).  You may recall that all classes SmootLight take a
+            single python dictionary as an argument -- this is embodied by the
+            \texttt{Args} tag.  A dictionary is created from the XML at runtime
+            -- this dictionary would be: \texttt{{'Id':'echo',
+                'RenderToScreen':False}}
+            The id we specify is the id that we can reference this behavior by
+            later.  The \verb RenderToScreen  attribute specifies whether or not
+            outputs from this behavior should be directed to the screen (some
+                    behaviors act only as the building blocks for other
+                    behaviors, and are never rendered directly to the screen)
+
+    \section{Behavior Chains}
+        I have mentioned several times that the system allows for behaviors to
+        be chained together to create many different effects -- often the
+        ``motion'' effect and the ``coloring'' effects are two separate
+        behaviors.  The result you see on the screen are these two pieces
+        connected together.  This allows us to build up many different behaviors
+        from a library of simple pieces.  Let's look at how we actually
+        accomplish this.
+
+        Behavior Chaining is accomplished through the behavior chain class.
+        Here is an example of a behavior we declare (in XML) via a behavior
+        chain:
+        \begin{verbatim}
+        <Behavior>
+            <Class>behaviors.BehaviorChain</Class>
+            <Args>
+                <Id>runcolordecay</Id>
+                <Inputs>
+                    <Id>pygame</Id>
+                    <Id>randomLoc</Id>
+                </Inputs>
+                <ChainedBehaviors>
+                    <Id>colorchange</Id>
+                    <Id>running</Id>
+                    <Id>decay</Id>
+                </ChainedBehaviors>
+                <RecursiveHooks>{'running':'acceleratedie'}</RecursiveHooks>
+                <RenderToScreen>True</RenderToScreen>
+                <Mapper>gaussmap</Mapper>
+            </Args>
+        </Behavior>
+        \end{verbatim}
+
+        Note the importance of the `Id' field -- that is how we reference all
+        other components of the system.  Let's walk through what is going on
+        here.  We declare this behavior just like any other -- however, for
+        class, we specify \verb BehaviorChain .  The \verb Inputs  tag specifies
+        which inputs will be routed to this behavior.  In this case, it is
+        \verb pygame  and \verb randomLoc  , two previously declared behaviors.
+        Inputs from these behaviors will be passed to the behavior chain via
+        sensorInputs.  Next, we have the meet of this chain, the behaviors it is
+        composed of.  This states that first, an input is routed through
+        \texttt{colorchange}.  \verb colorchange adds a color field to the
+        sensor data.  Next, the input is routed to \verb running  a behavior
+        that makes pixels run back and forth.  Finally, the input is routed to
+        \verb decay  , a behavior that adds a decay ``PixelEvent'' that makes
+        individual pixels turn on and then decay.
+
+        The next item we see is \verb RecursiveHooks  .  This is a special
+        feature of the \verb BehaviorChain  that allows us to augment the
+        reccurences recursive events have.  We specify that we will augment the
+        recursive behavior of \verb running  with another behavior, 
+        \verb acceleratedie  which modifies increases the speed of the running
+        behavior, and stops the behavior after a certain number of iterations.
+        Note that recursive hooks take data in via their \textbf{external input}
+        port, and \textbf{not} their recursive port.
+
+        Finally, we state that this behavior will indeed be rendered directly to
+        the screen.  We also specify which PixelMapper we want to use.
+        
+        Phew.  This isn't as complicated as it sounds.  I promise.
+
+        \end{document}
diff --git a/docs/designDocs.tex b/docs/tex/ClassOverview.tex
index 8e62edc..00d55ec 100644
--- a/docs/designDocs.tex
+++ b/docs/tex/ClassOverview.tex
@@ -56,8 +56,7 @@
                     be named classname.params and look like a python dict
                     (\texttt{\{'key':value, 'key2':value2\}} )
                 \end{itemize}
-            Note that at this point, the only class using this functionality
-                is the PixelEvent class.}
+                }
             {No required parameters in argDict}
     \classDoc{PixelAssembler}{SmootCoreObject}{LineLayout, ZigzagLayout}{
         PixelAssembler is a class that defines the positions of lights.  It
@@ -103,17 +102,11 @@
     \classDoc{Behavior}{SmootCoreObject}{EchoBehavior, DebugBehavior}{
 Abstract class for a behavior.  On every time step, the behavior is passed the
 inputs from all sensors it is bound to as well as any recursive inputs that it
-spawned during the last time step.  Inheriting classes MUST define
-\texttt{processBehavior}.  \texttt{processBehavior} should return a list of dictionaries which
-define the properties of the light response.  The must return a location
-\texttt{PixelEvent} class.  Soon be be deprecated:\textit{They must give a location and
-color.  They may define a function pointer which defines a custom mapping.
-[More on this later.  Bug Russell if you want to do it].}
-Call \texttt{recursiveResponse} to queue a input on the next iteration with a dictionary
-argument.  This will be passed in via recursive inputs.}
+spawned during the last time step.  Inheriting classes MUST define \texttt{processResponse}.  Look
+at the Behaviors documentation for more details.}
 {\begin{itemize}
     \item \texttt{Inputs}: A list of input Ids specifying input to the
-        behavior.  In the future, this may also contain behavior ids.
+        behavior.  
 \end{itemize}}
 \classDoc{PixelEvent}{SmootCoreObject}{StepResponse}{
     Abstract class defining the behavior of a light after it has been turned on.
@@ -155,6 +148,7 @@ argument.  This will be passed in via recursive inputs.}
         directly, unless you really know what you're doing.  Well, actually you
             should never need to do that.
         never.  Don't do it.}{Takes a \texttt{LayoutBuilder} as an argument.}
+    \end{itemize}
     \section{Best Practices}
         \subsection{Variable and function naming}
             I'm pretty bad about being consistent.  However, in all future