#
#                                    _JNJ`                    
#                                .JNMH`                       
#                               JMMF`       `;.               
#                             .NMM)          `MN.             
#                             MMM)            (MML            
#                            (MMM`             MMML           
#                      M  I  D  N  I  G  H  T    C  o  D  E   
#                            (NMMF             MHNH           
#                             NMML            .MMM            
#                              NMML          .NMH             
#                               4MMNL       .#F               
#                                `4HNNL_   `                  
#                                    `"""`                    
# 
#                           Copyright (C) 2004-2010
#        "Ian (Larry) Latter" <ian dot latter at midnightcode dot org>
# 
#     Midnight Code is a registered trademark of Ian Latter.
# 
#     This program is free software; you can redistribute it and/or modify
#     it under the terms of the GNU General Public License as published by
#     the Free Software Foundation, and mirrored at the Midnight Code web
#     site; as at version 2 of the License only.
# 
#     This program is distributed in the hope that it will be useful,
#     but WITHOUT ANY WARRANTY; without even the implied warranty of
#     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
#     General Public License for more details.
# 
#     You should have received a copy of the GNU General Public License
#     (version 2) along with this program; if not, write to the Free
#     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
#     02111-1307 USA, or see http://midnightcode.org/gplv2.txt
# 


-- About -------------------------------------------------------------------

  This program (klirc) provides a gesture-to-lirc interface for the Kinect,
  under Linux.  It will work with any lirc interfacing program, but has 
  been built/tested for MythTV.

  The program itself was an experiment kicked off by the open sourcing of 
  the Kinect, as sponsored by Adafruit (Thank-you Adafruit!). My friend and
  I acquired Kinect devices on his birthday in November, to experiment with
  its features.  I don't own an Xbox, and acquired the Kinect primarily to
  see if it really was possible to create a "wave remote" for MythTV, like
  the 2009 brochure-ware videos of Natal seemed to be promising.  In a
  bitter twist of irony, my friend's Xbox red-ringed a week after he bought
  the Kinect, so his Mac has seen more Kinect action than his Xbox ;-)


-- Controls ----------------------------------------------------------------

  The user interface controls have been mapped identically to the recently
  released "KinEmote" (of which I am not affiliated).  I will publish an
  instruction guide, but for now the KinEmote guide is just as useful;

    http://kinemote.googlecode.com/files/KinEmote%200.3%20Instructions.pdf

  Summary:

    The awake gesture is a "front-back" motion toward the Kinect with an
    open hand (palm facing the Kinect).  Where the hand comes "back" to,
    in space, becomes the centre of the mid plane.

    Front Plane:
                  Centre:  Enter

    Mid Plane:
                  Left:    Left
                  Right:   Right
                  Up:      Up
                  Down:    Down

    Back Plane:
                  Left:    Escape
                  Right:   Pause/Play (P)
                  Up:      Menu	(M)
                  Down:    [Ignore]


-- Usage -------------------------------------------------------------------

  To generate lircd.conf from this configuration, run;
     ./klirc -l > /etc/lirc/lircd.conf

  To run lircd as a UDP listener;
     lircd --driver udp

  To generate a mythtv lircrc file, run;
     ./klirc -m > ~/.lirc/mythtv

  To run klirc with a local (pwd) config file, run;
     ./klirc

  If the mythtv frontend server isn't localhost, then change the
  lirc_server entry in the klirc.cfg configuration file. 


-- Build -------------------------------------------------------------------

  The following build process works under Ubuntu 10.10 (32bit and unpatched,
  IIRC); with the caveat that the development and testing that I've done
  have been against an unreleased libmidnightcode version (1.6), though 1.5
  should be equivalent in all necessary regards.

  To begin, download the following Natural Interface frameworks, and 
  MidnightCode software to your home directory;

  http://openni.org/sites/default/files/OpenNI-Bin-Ubuntu-x86-1.0.0.23.tar.bz2
  http://downloads.primesense.com/NITE-Bin-Ubuntu-x86-1.3.0.17.tar.bz2
  http://midnightcode.org/projects/libmidnightcode/code/libmidnightcode-1.5.tgz
  http://midnightcode.org/projects/jupiter/code/klirc-1.0.tgz

  Install and test the Natural Interface frameworks;

   Step 1) Install OpenNI;
            0) cd ~
            1) mkdir openni
            2) cd openni
            3) tar xvfj ../OpenNI-Bin-Ubuntu-x86-1.0.0.23.tar.bz2
            4) sudo ./install.sh

   Step 2) Install NITE;
            0) cd ~
            1) mkdir nite
            2) cd nite
            3) tar xvfj ../NITE-Bin-Ubuntu-x86-1.3.0.17.tar.bz2
            4) cd Nite-1.3.0.17
            5) sudo ./install.bash
            6) [enter key: 0KOIk2JeIBYClPWVnMoRKn5cdY4=]

   Step 3) Install Sensor;
            0) cd ~
            1) mkdir sensor
            2) cd sensor
            3) git clone git://github.com/avin2/SensorKinect.git
            4) cd SensorKinect/Platform/Linux-x86/CreateRedist
            5) ./RedistMaker
            6) cd ../Redist
            7) sudo ./install.sh

   Step 4) Run the OpenNI demo;
            0) cd ~
            1) cd openni/Samples/Bin/Release
            2) sudo ./NiViewer

   Step 5) Run the NITE demo;
            0) cd ~
            1) cd nite/Nite-1.3.0.17/Samples/Bin
            2) sudo ./Sample-PointViewer

  Install the Midnight Code software;

   Step 6) Install libMidnightCode;
            0) cd ~
            1) mkdir libmc
            2) cd libmc
            3) tar xvfz ../libmidnightcode-1.5.tgz
            4) cd libmidnightcode-1.5
            5) make
            6) make install
 
   Step 7) Build and klirc program;
            0) cd ~
            1) cd nite/Nite-1.3.0.17/Samples
            3) tar xvfz ../klirc-1.0.tgz
            4) cd klirc-1.0
            5) make

  At this point, running ./klirc from the ~/nite/Nite-1.3.0.17/Samples
  directory, should show success (if the Kinect is USB connected and
  powered).


-- Thanks ------------------------------------------------------------------

  To John Pimble for the lirc-udp.pl program;
    http://www.dddgames.com/japi/blogfiles/lirc-udp.pl

  To trtg for the NITE mouse program;
    http://www.keyboardmods.com/2010/12/howto-use-kinect-as-mouse-in-linux.html

  To my friends for their support.

  Oh, and Happy Birthday Gus - lol.


