From 84d914b0a015ef6c588253ac7f70382bfa9030e5 Mon Sep 17 00:00:00 2001
From: rcoh <rcoh@mit.edu>
Date: Tue, 15 Feb 2011 15:15:43 -0500
Subject: Added documentation to repo in docs folder.

---
 docs/tex/ClassOverview.tex | 186 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 186 insertions(+)
 create mode 100644 docs/tex/ClassOverview.tex

(limited to 'docs/tex/ClassOverview.tex')

diff --git a/docs/tex/ClassOverview.tex b/docs/tex/ClassOverview.tex
new file mode 100644
index 0000000..00d55ec
--- /dev/null
+++ b/docs/tex/ClassOverview.tex
@@ -0,0 +1,186 @@
+\documentclass{article}
+\usepackage{fullpage}
+\begin{document}
+    \title{150 Smoots Lighting Installation Design Document}
+    \author{Russell Cohen}
+    \date{\today}
+    \maketitle
+    \newcommand{\classDoc}[5]{
+        \subsection{#1}
+            \begin{itemize}
+            \item \textbf{Inherits from: } #2 
+            \item \textbf{Inherited by: } #3 
+            \item \textbf{Brief Description: } #4 
+            \item \textbf{Argument Requirements: } #5
+            \end{itemize}
+        }
+    \section{Intro}
+        \textbf{NB: These docs give an overview of the classes and methods but
+            may lag behind the code for certain in-flux functionality.  For
+                up-to-the minute docs, please use pydoc.} \\
+        The system, which we will describe henceforth as SmootLight is a
+        modular system designed with the following goals in mind:
+        \begin{itemize} 
+            \item The system must abstract away from all components while
+            remaining useful (\verb=Renderer=, \verb=Input=, \verb=Behavior=) 
+            \item The system must be modular and be easy to write new code for.
+            \item More goals as I think of them
+        \end{itemize}
+        We accomplish this in the following manner:
+        \begin{itemize}
+            \item The system is configured by an XML file which specifies its
+            components.
+            \item All classes are initialized with a dictionary as an argument
+                containing anything a class may need.  All objects are passed
+                between members as python dictionaries because their easy
+                serialization.
+        \end{itemize}
+    \section{Overview}
+        \begin{itemize}
+            \item
+    \section{Operations Class Patterns}
+    \classDoc{SmootCoreObject}{None}{All 2nd level classes (PixelAssembler, Renderer,
+                Input, Behavior)}
+    {SmootCoreObject is essentially a super-object
+            that makes things easy for us.  It does the following actions:
+                \begin{itemize}
+                    \item Defines a constructor that sets argDict
+                    \item Defines a \texttt{\_\_getitem\_\_} , which lets us acces items in
+                    argDict as if the class was a dictionary.
+                    (\texttt{self['itemName']}).  It also automatically maps the
+                    initial contents of the argDict to class attributes.
+                    \item Defines validateArgs and validateArgDict which
+                    validate the incoming arguments against a dictionary
+                    containing argument names as keys and an error message to
+                    display if they are missing as a values.  This file should
+                    be named classname.params and look like a python dict
+                    (\texttt{\{'key':value, 'key2':value2\}} )
+                \end{itemize}
+                }
+            {No required parameters in argDict}
+    \classDoc{PixelAssembler}{SmootCoreObject}{LineLayout, ZigzagLayout}{
+        PixelAssembler is a class that defines the positions of lights.  It
+            provides a method \texttt{getLightLocations} which give a list of
+            all light locations for a given strip.  Inheriting classes must
+            define \texttt{layoutFunc} which returns the next location given the
+            previous location.  (They may simply override
+                    \texttt{getLightLocations}
+                    instead, if they wish, but be careful when doing so).  In
+            heriting classes may defint \texttt{initLayout} which is called at
+            initialization.}{\begin{itemize}
+                \item \texttt{lightToLightSpacing}: this is the length of wire
+                    between 2 adjacent LEDs.  Common values are 4 or 12.
+                \item \texttt{numLights}: Number of lights in a strip.
+                \item \texttt{originLocation}: Location of the first light.
+                \end{itemize}}
+    \classDoc{Renderer}{SmootCoreObject}{PygameRenderer, IndoorRenderer}{
+        Renderer is a class that serves as an abstract class for renderers
+            interacting with the system.  Inheriting classes must define
+            render, which is passed a \texttt{lightSystem} object.  Inheriting
+            classes may define initRenderer which is called on initiation.
+    }{No required arguments}
+    \classDoc{Input}{SmootCoreObject, threading.Thread}{PygameInput,
+        TCPInput,UDPInput}{Input is a abstract class which facilitates Inputs.
+            It does this by providing a method that is polled at a periodic
+                interval within which the inheriting class can raise an event.
+                Inheriting classes must define \texttt{sensingLoop} which is
+                called at the interval specified in the config.  Inheriting
+                classes should call respond with an dictionary as an argument
+                to raise an event.  Classes using (not
+                        inheriting) input must pass a scope into
+        the argDict which offers a \texttt{processInput}
+            method.  Inputs are marked as Daemon threads, and
+                are therefore killed when their parent is
+                killed.}{\begin{itemize}
+                    \item \texttt{InputId}: The string id of a given input.  Must be
+                        unique.
+                    \item Optional:\texttt{RefreshInterval}: The interval in
+                    seconds (will soon be changed to milliseconds) between
+                    sucessive calls to the sensingLoop method.  TODO: make
+                    timeout.
+                \end{itemize}}
+    \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{processResponse}.  Look
+at the Behaviors documentation for more details.}
+{\begin{itemize}
+    \item \texttt{Inputs}: A list of input Ids specifying input to the
+        behavior.  
+\end{itemize}}
+\classDoc{PixelEvent}{SmootCoreObject}{StepResponse}{
+    Abstract class defining the behavior of a light after it has been turned on.
+        Inheriting classes should defint \texttt{lightState} which is passed a
+        timeDelay in ms as an argument.  \texttt{lightState} should return a
+        color or None if the response is complete.}{\begin{itemize}
+            \item \texttt{Color}: The color of response.  \textit{This is may be
+                removed in the future}
+            \end{itemize}
+        }
+\section{The Screen Class and Its Relatives}
+\classDoc{Screen}{None}{None}
+{The \texttt{Screen} class is a representation of an entire system of pixels,
+    distributed over space.  The Screen class and its relatives process
+        responses (mapped to pixels via a LayoutEngine), and add PixelEvents
+        to the individual pixels.  The Screen provides an instance that
+        renderers can call to determine the color of all the individual pixels. It contains a list of PixelStrips, which each
+        address the individual pixels.  \texttt{Screen} offers a
+        \texttt{respond} method which takes a dictionary containing information
+        about a response.  TODO: detail the contents of this dictionary (maybe
+                somewhere else).  Note: \texttt{Screen} will not process its
+        responses until \texttt{timeStep} is called which processes all responses that
+        have been queued since the last time that \texttt{timeStep} was
+        called.  Screen also offers an iterator over \textit{all} lights,
+    accesible by using an expression like: \texttt{for light in screen:}.  For
+        addressing of specific \texttt{PixelStrips} , \texttt{self.pixelStrips}
+    is exposed.}{No required parameters}
+\classDoc{PixelStrip}{None}{None}
+{The \texttt{PixelStrip} class is a representation of a string of Pixels that are
+    connected in physical space (eg. a strip of lights).  A \texttt{PixelStrip} takes a
+        \texttt{LayoutBuilder} (\textit{Name up for debate, currently known as layout
+            engine}) as an argument.  The \texttt{argDict} of the
+        \texttt{LayoutBuilder} is
+        passed becomes the \texttt{argDict} of the \texttt{PixelStrip}.
+        \texttt{PixelStrip} generally shouldn't be
+        adressed directly unless you need Strip-Identification for rendering
+        purposes.  You should never, for example, call \texttt{respond} on a
+        \texttt{PixelStrip}
+        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
+            code, please adhere to the following:
+            \begin{itemize}
+                \item Classes: \texttt{FirstLetterCaps}
+                \item Functions: \texttt{camelCase}
+                \item Property Names: \texttt{FirstLetterCaps}
+                \item Constants: \texttt{ALL\_CAPS\_WITH\_UNDERSCORES}
+            \end{itemize}
+        \subsection{Time}
+            For time, use the \texttt{util.TimeOps.time()} method to return the current
+            time in ms.
+        \subsection{Acessing a Component Given an Id}
+            Use \texttt{util.ComponentRegistry.getComponent(id)}.  This provides any
+            component access to any other components.  We may consider a way to
+            make this read-only.
+        \subsection{Acessing Pixels}
+            The ideal method for acessing Pixels in a screen is to use its
+            iterator.  Iterating over the individual PixelStrips is also an
+            acceptable method.  
+        \subsection{Determining the state of a \texttt{Pixel}}
+            The best practice for determining the color of a \texttt{Pixel} is to call
+            \texttt{state}.  This ensures
+            all current active responses running on the Pixel contribute correctly. 
+        \subsection{Color}
+            For color, use a tuple of (R,G,B) 0-255 for each.  Colors can be
+            easily manipulated with members of the Util class.
+        \subsection{Locations}
+            Locations are stored (x,y), in whatever unit you light system is
+            in.  (Whatever unit you use when you define spacing).
+        \subsection{Constant Strings (key strings, 'Location', 'Color', etc.)}
+            Use the util.Strings module.  It contains many currently in use
+            Strings, and ensures consistency. 
+    \end{document}
-- 
cgit v1.2.3

