setup.txt

I am updating this file on request, but it has been 3 years since I worked on this
project, and my memory is a bit hazy, so details may be missing or in error.
- Matthew Humphrey

Requirements / Pre-requisites

	Hardware
		* Super Feeder pet feeding machines (great company) - http://super-feeder.com/
		* Raspberry Pi - http://www.raspberrypi.org/
		* Edimax WiFi module for Raspberry Pi. I had lots of issues with the Edimax 
		  dropping the WiFi connection. There may be better alternatives now.
		* Microsoft LifeCam (Any number of USB webcams will work)
		* Raspberry Pi breadboard PCB - http://www.adafruit.com/products/1148
		* N-channel MOSFET, diode, optocoupler, wires, mini-din socket, micro-usb cable, 
		  and some passive components to make a circuit to control power to the treat feeder.
		  If you are not comfortable with electronics, I would look into using an 
		  off-the-shelf Solid State Relay (SSR) instead. 
		* 2 line x 16 character serial LCD - https://www.parallax.com/product/27977.
		* A custom "Treat detector" circuit. This is something of my own design, and consists
		  of a 555 timer, some passives, and a small (2.5 cm) piezoelectric disc. The 
		  piezoelectric disc is used to detect the impact of treats hitting the dispensing
		  bowl. The 555 timer and other circuitry turn this into pulses that are fed
		  into one of the Raspberry Pi GPIO ports. This allows the software to count the
		  treats that are dispensed. 

	Software
		* Raspbian OS
		  https://www.raspberrypi.org/downloads/
		  http://www.raspbian.org/
		* Raspberry PI GPIO support. I was unable to get the simple Python-enabled
		  GPIO library to work as non-root, so I installed this 3rd-party package
		  that sets up sysfs entries for GPIO, and then enabled non-root access
		  with a UDEV rule. I am sure the situation has improved since I did all this,
		  so you'll probably want to go another route.
		* Motion - software that detects motion in a camera and captures an image.
		  At the time I created this project, there was a supported version of this
		  software for the Raspberry Pi. There may be better alternatives now. All that 
		  is needed is some software to capture images from a USB webcam, and write
		  those images to a configured directory if motion is detected.
		  http://www.lavrsen.dk/foswiki/bin/view/Motion/
		* Nginx HTTP Server and Reverse Proxy server. Python makes for a terrible web
		  server. Late in the project, I added Nginix to serve all my static content, and
		  to proxy only those requests requiring dynamic content through to Python. Nginix
		  can also be used to provide HTTPS, and to require the user to authenticate,
		  so that you have some level of security.
		  http://nginx.org/
		* Python. I don't remember if it was 2.7 or 3.0.
		* Python serial library (pyserial - install with pip)
		* Python Imaging Toolkit - install with apt.
		* Twisted - An event driven framework for Python. I migrated to this after 
		  experiencing horrible performance and lock-ups with the Python web library. 
		  Possibly it is not needed after adding Nginx, but the code included in the 
		  project is all using it. 
		  http://twistedmatrix.com/trac

Basic Set-up for a Noob

	* Set up the Raspberry Pi SDCard image, following the instructions available on numerous web sites.
	  I am not a big fan of the "Noobs" distro on the RPi site, and recommend using Raspbian 
	  instead.
	* Set up networking on the Raspberry Pi, either wired ethernet or Wifi.
	* Install Motion, and get it working to capture images from your USB web cam.
	* If necessary, install the Raspberry Pi GPIO library for Python. Write a small program
	  to interact with GPIO. Make sure this program can run as non-root user, because you will
	  most likely want this later so that you don't have some service sitting on the Internet
	  with root access to the Pi. There is an included UDEV rule that should help with this,
	  but things may have changed over the last 3 years, and so it may or may not work. 
	* Install the Python serial port library. Connect your LCD to the RPi, and write some text
	  to it using a Python programming. By default, the RPi uses the default serial port on the
	  RPi for the Linux Console. Instructions are available on the RPi site on how to disable
	  that, so that the device is available for your use.
	* Install Nginx. Read the docs, learn the basics.
	* Install Twisted, go through the tutorials, learn the basics.

Treater Web App Configuration

    The treater app consists of some Python modules, and some static HTML content. I have
    the app set up to run as a user named "treat". All the python modules and static HTML
    content reside within this user's home directory. The user does not have access to
    anything else, and has logon rights denied. This provides a little extra security
    over having everything running as root.

    Within this home directory (/home/treat), the folder structure is as follows:

    	captures/
    	htdocs/
    		css
    		images/
    		js/
    	treater/

    The "captures" folder contains images captured by the Motion daemon. 
    The "htdocs" folder contains all the static HTML content, serviced by Nginx.
    The "treater" folder contains all the Python modules. 

    Note that the directory structure in the GitHub repo is not identical to this. In
    other words, you will need to create the user, create the directory structure, and
    copy some files to the appropriate places to get this all working.
			
    There is an init.d script, named "treater" that runs Python on the treater
    script when the system starts. This daemon process is responsible for all
    dynamic content on the web site. The configuration file for this application,
    treater.cfg, lives in /etc. This file, which is fairly well commented, tells
    the script what network (TCP) port it should listen on, where to look for
    capture files, etc. 

    Nginx is configured to server the static content, and to proxy all requests
    with /api/ in the path to the treater app, on localhost at the configured port
    (8000). It is also configured to proxy any requests to /video to localhost port
    8002. Motion has been configured to serve "video" (really low frame rate video)
    on this port. This is how the live view works.

Treater Web App - Python Module overview

   	__init__.py
   		Global initialization for the treater package. Tells Python that this folder 
   		is a package/module.

   	__main__.py
   		Main entry point for the application.

   	camera.py
   		This module abstracts the interface to the Motion captures. It implements a
   		class, TreatCam, that provides methods to:
   			- Trigger a capture on-demand
   			- Prune old capture files from the capture directory
   			- Determine the latest captured image file
   			- Return the date/time of the latest capture

   	gpiosys.py
   	    This is my wrapper around the /dev sysfs GPIO mechanism mentioned above.
   	    You'll probably want to rewrite this to use something more up to date.

   	history.py
   	    This module captures the treat dispensing history into a file that
   	    persists across reboots. 

   	machine.py
   	    This module implements classes that abstract all control of the treat
   	    dispensing machine. It implements a finite state machine to manage the 
   	    treat dispensing cycle (the machine I was using had a period after 
   	    dispensing in which another treat could not be dispensed). It has methods
   	    to dispense a treat, to detect if the manual dispense button was pressed,
   	    and to update the LCD (using the class in seriallcd.py).

   	raspicam.py
   	    This is a holdover from the previous version of the app - ignore. In case
   	    you are interested, I initially was using the Raspberry Pi cam, but 
   	    discovered that the software for it was a complete and total piece of
   	    garbage, rendering the camera next to useless. That's when I switched to
   	    the USB cam and started using Motion. You can probably still find my
   	    forum thread up on raspberrypi.org, in which I really ticked off the 
   	    RaspiCam guy :)

   	seriallcd.py
   	    Abstracts the interface to the serial LCD.

    website.py
        This module contains all the entry points for web calls that come from
        Nginx. For example, when you use the web UI to trigger a treat, the
        web page references a URL ending in /api/dispensetreat. Nginix proxies
        this to the Python app that is running in the background. This goes
        through the Twisted framework, and ends up in the class ApiDispenseTreat,
        method render_POST. If you look at that code, you can see that it calls
        a method in the TreatMachine class (in machine.py) called dispenseTreat.
        This method either dispenses a treat, or returns an error indicating
        that the machine is still recovering from a previous dispense cycle.


================================ OLD INFO ==========================================
Everything below this line is from my V1 version of this app, before I made many 
changes. Some parts are still relevent, others are out of date.
================================ OLD INFO ==========================================


Initial Set-up     

	Set up Raspberry Pi.  I was using Occidentalis, but it is not kept up-to-
	date, and it doesn’t add anything that you can’t install on Raspbian
	later. So I would just recommend using Raspbian. Instructions are on the
	Raspberrypi.org site.

	Boot and log in: pi / raspberry
	Run raspi-config (should come up on its own or use sudo raspi-config)
		Expand file system
		Enable camera
		Set locale: en-us (UTF-8)
		Set keyboard map to US
		Set timezone
		Overclock if desired
		Change pi password (or delete account later)
	
Add a new user
	sudo adduser user
	
	Add account to sudo list:
		sudo visudo
	
Update the system
	Update the package list:
		sudo apt-get update
	
	Update the distribution:
		sudo apt-get upgrade
		
Update the firmware:
	sudo apt-get install rpi-update
	sudo rpi-update
	
Configure WiFi (if applicable):
	sudo nano /etc/network/interfaces
	
	Mine looks as follows (bold items are relevant):
	
		auto lo
		
		iface lo inet loopback
		
		iface eth0 inet dhcp
		
		auto wlan0
		allow-hotplug wlan0
		iface wlan0 inet manual
		        wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
		
		iface default inet dhcp
	
	Create or edit wpa_supplicant.conf:
		sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
	
	Contents of this are as follows:
	
		ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
		update_config=1
		
		network={
		        ssid="YOUR_AP_SSID"
		        scan_ssid=1
		        proto=RSN
		        key_mgmt=WPA-PSK
		        pairwise=CCMP
		        auth_alg=OPEN
		        psk="your_wpa2_key"
		}
		
	This will set things up for WPA-2. If you need something else, Bing for it.
	
Non-root access to raspberry pi camera
	Add users to video group:
		sudo usermod -aG video user
	
	Create udev rule to set permission of vchiq device:
		sudo echo 'SUBSYSTEM=="vchiq",GROUP="video",MODE="0660"' > /etc/udev/rules.d/10-permissions.rules

Enable access to serial port:
	The serial port device is /dev/ttyAMA0. The main issue is that the OS has a console attached to it, so it isn't available for user-space programs to use. To change this, we need to update the kernel command line. Make a back-up of /boot/cmdline.txt:
		sudo cp /boot/cmdline.txt /boot/cmdline_backup.txt
	
	Then edit the file:
		sudo nano /boot/cmdline.txt
	
	Delete the following strings and save the file:
		console=ttyAMA0,115200 
		kgdboc=ttyAMA0,115200
	
	Then remove the reference to this device from /etc/inittab:
		sudo nano /etc/inittab
		
	Comment out or remove this line:
		T0:23:respawn:/sbin/getty -L ttyAMA0 115200 vt100
	
	Add user to group (dialout) that has access to /dev/ttyAMA0 (not strictly sure this is needed):
		sudo usermod -aG dialout user

If using the Edimax or other 8192cu module
	You can check which USB network device is there by running this command:
		lsusb
	
	For the two different adapters I have, here is what was displayed:
		? Bus 001 Device 004: ID 7392:7811 Edimax Technology Co., Ltd EW-7811Un 802.11n Wireless Adapter [Realtek RTL8188CUS]
		? Bus 001 Device 002: ID 0bda:8176 Realtek Semiconductor Corp. RTL8188CUS 802.11n WLAN Adapter
	
	You can see they are both using the same chip: RTL8188CUS. The driver for this is 8192cu. 
	
	This OS/driver will put the device in low power mode if it is idle long enough. This is a PITA because it prevents you from SSH into the Pi. Since I typically am using a Pi in a headless configuration, this just won't do. To fix this, we need to tell the driver to disable power management. How you do this depends on whether it is loaded as a module or compiled in the kernel. You can tell by running this command:
		lsmod
	
	If you see "8192cu" in the list of loaded modules,  then the driver is loaded as a module. If not, then it is either compiled in the kernel, or you have a different network adapter.
	
	You can confirm that power management is enabled by running this command:
		cat /sys/module/8192cu/parameters/rtw_power_mgnt
	
	A value of "0" means power management is disabled. "1" means minimum power management and "2" means max power management.
	
	If loaded as a module, create or edit a module configuration file in /etc/modprobe.d:
		sudo nano /etc/modprobe.d/8192cu.conf
	
	Add the following lines:
		# Disable power management
		options 8192cu rtw_power_mgnt=0 rtw_enusbss=0 
		
	If compiled in the kernel:
		Add the following string to /boot/cmdline.txt:
			8192cu.rtw_power_mgnt=0 8192cu.rtw_enusbss=0 
	
Install Python serial port library
	sudo apt-get install python-pip
	sudo pip pyserial
	
Install Python Imaging Toolkit
	sudo aptitude install python-imaging-tk
	
Set hostname
	sudo nano /etc/hostname
	
Reboot
	sudo reboot
	
Install Application
	• Extract the source into the root of the home directory for the user you created to run the service. 
	• Create a directory, treater, under /var/log/. Change owner and group to user.user where user is the user you created to run the service under. Make sure to set permissions to this directory so that only this user has access (otherwise logrorate will complain).
	• In the setup directory, are several files that you can use as examples to set up logrotate, an init script, and udev. 

Install Twisted (see http://twistedmatrix.com/trac)