added basic documentation

Author: mzuther

doc/PythonMcu.pdf

@@ -0,0 +1,158 @@
+\input{include/settings.sty}
+\input{include/hyphenation.sty}
+
+\title{Python MCU}
+\author{Martin Zuther}
+
+\begin{document}
+
+\title{Python MCU}
+
+\subtitle{
+  \normalsize{\textrm{\textmd{
+        \vfill
+        Mackie Host Controller written in Python
+        \vfill
+        \vspace{10em}
+        \vfill
+      }}}
+}
+
+\author{\normalsize\copyright{} 2011
+  \href{http://www.mzuther.de/}{Martin Zuther}}
+
+\date{\normalsize \emph{Last edited on \today}}
+
+\maketitle
+
+\tableofcontents
+
+\clearpage  % layout
+
+\chapter{Mackie Control}
+\label{chap:mackie_control}
+
+\textbf{Mackie Control} (abbreviated to MCU), its predecessor
+\textbf{Logic Control} and their respective extension units
+(\textbf{XT}) are control surfaces that use a proprietary MIDI
+protocol to control digital audio workstations (DAWs), especially
+their mixing sections.  However, these control surfaces have two
+drawbacks: they are definitely not cheap and require quite a bit of
+space.  If these are no restrictions to you, by all means go and try
+them.  But don't stop reading here, as this application might be
+useful for Mackie Control users as well.
+
+If, on the other hand, you have a certain lack of money or available
+space (or you have a controller that is simply too good to be
+exchanged for an MCU), you might have found just the application you
+need.  It might not support your MIDI hardware controller yet, but if
+you know a bit of \textbf{Python} (or a programmer) it's pretty easy
+to change that.
+
+
+\chapter{Installation}
+\label{chap:python_mcu}
+
+Download and install the latest version of
+\href{http://www.python.org/}{Python 2.6} on your computer.  As of
+August 2011, there is no installer of Python 2.6.7 for Microsoft
+Windows yet.  Users of this operating system may download
+\href{http://www.python.org/download/releases/2.6.6/}{Python 2.6.6},
+instead.
+
+Please also download and install these libraries:
+
+\begin{compactitem}
+\item \href{http://www.pyside.org//}{PySide} (version 1.0.5 or above)
+\item \href{http://www.pygame.org/}{pygame} (version 1.9.1 or above;
+  please note that pygame's MIDI implementation is still in its
+  infancy and may occasionally crash \application{Python MCU})
+\end{compactitem}
+
+You'll also need virtual MIDI ports or cables to connect
+\application{Python MCU} to your DAW and hardware controller.  I have
+successfully used \application{MidiYoke NT} (Microsoft Windows) and
+\application{JACK} (GNU/Linux), but others may work just as well.
+
+When you're done, simply run the file \path{PythonMcu.py} in the
+directory \path{src} by either double-clicking it or starting a
+console window, moving to the directory \path{src} and running
+\texttt{python PythonMcu.py}.
+
+
+\chapter{Tested configurations}
+\label{chap:tested_configurations}
+
+\section{Hardware controllers}
+
+\begin{compactitem}
+\item Novation ZeRO SL MkII
+\end{compactitem}
+
+\section{Microsoft Windows XP}
+
+\begin{compactitem}
+\item Ableton Live 8
+\item Cockos Reaper 4
+\item Emagic Logic 5
+\end{compactitem}
+
+\section{Apple Mac}
+
+I haven't got a Mac, but things should work just as well.  Please
+report working configurations to me.  Thanks!
+
+\section{GNU/Linux}
+
+\begin{compactitem}
+\item ardour 2 \emph{(skipped a lot of commands, though)}
+\end{compactitem}
+
+\chapter{Extending Python MCU}
+\label{chap:extending_python_mcu}
+
+\application{Python MCU} consists of three parts:
+
+\begin{itemize}
+
+\item the \textbf{MackieHostControl} class communicates with a
+  connected sequencer using the Mackie Control protocol, translating
+  the raw protocol to something much easier to read and use
+
+\item the generalised \textbf{MidiControllerTemplate} class and its
+  more specific relatives handle all the details of sending data to
+  and receiving data from your hardware controller, again translating
+  raw protocols to something easier to read and use
+
+\item finally, the \textbf{McuInterconnector} class connects the
+  \textbf{MackieHostControl} and \textbf{MidiControllerTemplate}
+  classes (and thus your DAW and hardware controller) with each other
+
+\end{itemize}
+
+This modular design means that the application happily works away with
+the irrelevant implementation details being effectively hidden from
+you.  As long as you adhere to the internal protocol, you may easily
+extend \application{Python MCU} by deriving a class from
+\textbf{MidiControllerTemplate} to include your own controller.
+
+If all this means nothing to you, go find yourself a Python programmer
+(or learn Python yourself, it's rather easy and a lot of fun!).  As
+long as you know the relevant MIDI implementation of your hardware
+controller and worked out a suitable layout of its buttons and
+controllers, hooking into \application{Python MCU} is pretty simple.
+If you don't believe me, just have a look into the \path{src/Hardware}
+directory.
+
+\input{include/gpl_v3.tex}
+
+\end{document}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% mode: outline-minor
+%%% TeX-command-default: "Rubber"
+%%% TeX-PDF-mode: t
+%%% ispell-local-dictionary: "british"
+%%% End: