**
************************************************************************************
**      CodeChix PiDoorbell - Home Automation with RaspberryPi using GPIO
**      codechix.org - May the code be with you...
**              2013-2014
************************************************************************************
**
** License:       	GPL v2
** Version:        	1.0
** Project/Library:	PiDoorbell
** Description:    	Top level README - individual subdirs
**                 	might also have their own README files
** Assumptions:    	You know Python and Linux basics. And you like to fiddle with hardware.
** Testing:        	Limited - needs lots of testing
** Authors:        	Rupa Dachere, Akkana Peck, Deepa Dhurka, Serpil Bayraktar
**
** Main Contact:   rupa@codechix.org
** Alt. Contact:   organizers@codechix.org
**
** Additional acknowledgements:  Akkana Peck - modifications to the HC_SR04.py script
**					for averaging of sensor readings, creation of
**					piphoto.py to support PiCamera module and 
**					modularize USB Webcam code from 
**					pidoorbell-recognizer-gpio.py
**				 Deepa Karnad Dhurka, Serpil Bayraktar, Rupa Dachere: 
**					For FAQ's
**				 Rupa Dachere, Akkana Peck, Deepa Dhurka:
**					Handouts &  Presentation slides
***********************************************************************************
**


This is PiDoorbell version 3.0
==============================
Version 1.0 - Supports photos with Arduino
Version 2.0 - Supports video/audio clip with Arduino
Version 3.0 - Supports GPIO without Arduino - specifically for 2014 tutorial/workshop

Copyright: CodeChix 2013-2014
==============================
PiDoorbell was created by Rupa Dachere in January 2013 and went through
several revisions (v1-3).  This is a live project and is subject to random
updates with new features and bugfixes.

License information
=====================
PiDoorbell license: GPL v2

What’s new in this release?
=====================
This is version 3.0 which removes the reliance on the Arduino Uno R3 and 
connects the proximity sensor directly to the RaspberryPi via GPIO.  It
captures photos as well as video/audio clips.


Documentation
=====================

For the tutorial, take a look at the "Docs" dir/folder.

What software you get and what you need to create
--------------------------------------------------

1. What you get
 	
	You will get the PiDoorbell code that runs on the RaspberryPi and
	connects to the proximity sensor and USB camera so that you can take
	photos or video/audio clips.  This includes
		pidoorbell-recognizer-gpio.py - main code for detection, notification
		send-notifications.py - code to send tweet, sms etc.
		sms_auth_info.py - authentication keys and tokens for Twilio, Twitter, Dropbox
		dropbox_uploader.sh - script to upload photo/video to Dropbox
		dropbox_token.txt - file containing dropbox uploader tokens
		HC_SR04.py - standalone script to read sensor data
                piphoto.py - module to handle still photos via USB or RPi camera

2. What you will need to create/modify

	(a) In order for notifications to be tweeted/sms'd as well as uploading
		of photos/videos, you will need to create accounts on Twitter, Twilio
		and Dropbox.
		You will need to get your API keys and tokens/secrets from each of these services and modify
		the file called "sms_auth_info.py".  This should be in the same dir/folder as (1).
		If you want to use any other service/API, you will need to put the authentication
		tokens and secrets in this file.  Although the filename might indicate sms content, this
		file holds information on all services.  I might change the filename at some point if this
		turns out to be a bit of a stumbling block for people.

	(b) You will also need to create a directory to store your video/audio clips to upload
		to Dropbox.  Do:
		"mkdir -p dropbox-pidoorbell; chmod 744 dropbox-pidoorbell"

        (c) Download the Dropbox Python SDK and install it.  This is used by the dropbox_uploader.sh
		script to upload and share the file/url.
		"curl "https://raw.github.com/andreafabrizi/Dropbox-Uploader/master/dropbox_uploader.sh" -o dropbox_uploader.sh"
		chmod 744 dropbox_uploader.sh

	(d) You will need to get your Dropbox token and add it as the first and only line
		in the following file.  This should be in the same dir/folder as (1).
		dropbox_token.txt.  When you run the dropbox_uploader.sh script, you will
		get directions on how to get this info and add it to this file.

	 

How to run PiDoorbell from the command line
--------------------------------------------

Assuming you've cloned the repo and have all necessary packages installed (see Dependencies)
and have read & followed the documentation, you should be able to run pidoorbell as follows:

1. git clone git@github.com:codechix/PiDoorbell.git
 
2. sudo python ./pidoorbell-recognizer-gpio.py -h 
	This will provide you with help on the various options.  They are:
	  -i - Run in interactive mode
	  -latency - Latency in seconds if you want to increase the default of 20s
			to account for crappy wifi/network connectivity
			This is optional.
	  -pic_mode - Required field. Specify whether you want to take a Video Clip (1) or Photo (2). Defaults to Photo (2).
			This is optional.
	  -mode - Required field. This is the notification mode. Specify, "sms", "tweet" or "local".  The "local" mode will
			not use services like Twitter, Dropbox or Twilio.	

3. If you want to adjust the latency to account for slow bandwidth when uploading
	to Dropbox, append the latency value to the end of the command like:

   	"sudo python ./pidoorbell-recognizer-gpio.py -i -latency <latency_value> -pic_mode <1 or 2> -mode <sms or tweet or local>"

   	Note that the default latency is 20 seconds 

4. If you want to specify the picture mode for a video clip of 10 secs [1] or a
	snapshot/Photo [2], append the pic_mode value to the end of the command like:

   	"sudo python ./pidoorbell-recognizer-gpio.py -i -pic_mode <1 or 2> -mode <sms or tweet or local>"

   	Note that the default pic_mode is Photo (2).  Video Clip = 1.

NOTE: This code has not been tested in non-interactive mode so bugs may exist.

Web sites
==========
https://github.com/codechix/pidoorbell
http://codechix.github.io/PiDoorbell - web page


Bug report
==========

1. There is a bug with the sequential count (noise tolerance)
	where the count isn't tracked
2. Never tested in non-interactive mode

Supported systems
==========
Wheezy Raspbian - any release since Dec. 2012
USB camera - Logitech c270, c210
HC-SR04 sonar proximity sensor
Dropbox, Twilio, Twitter


Dependencies
==========

1. sudo apt-get install pip pyserial python-rpi.gpio git
2. Create Dropbox account. Download and Install Dropbox Python SDK (1.5.1 and up)
	https://www.dropbox.com/developers/core/sdks/python
3. Create Twilio account and save account ID and authentication keys in sm_auth_info.py
	Download & install Twilio SDK: http://twilio.com/docs/libraries
4. Create Twitter account. Download & Install python-twitter package - https://code.google.com/p/python-twitter/
	- python setup.py build
        - python setup.py install
    	- Test it: python setup.py test  or python twitter_test.py	
5. For photos, PiDoorbell uses fswebcam (should already be installed) or uvccapture
6. Download dropbox_uploader.sh sript - https://github.com/andreafabrizi/Dropbox-Uploader. 
      Please give him some money - he's done a great job.
   Run: curl "https://raw.github.com/andreafabrizi/Dropbox-Uploader/master/dropbox_uploader.sh" -o dropbox_uploader.sh
   Run: chmod 744 dropbox_uploader.sh
7. For video/audio, use ffmpeg (you can also try pyffmpeg - I haven't tried it).
8. Download and compile ffmpeg to capture video clips. I couldn't get avconf to work.: 
    	cd /usr/src/
    	git clone git://source.ffmpeg.org/ffmpeg.git
    	cd ffmpeg      
    	./configure --enable-shared --enable-gpl --prefix=/usr --enable-nonfree --enable-libmp3lame --enable-libfaac --enable-libx264 --enable-version3 --disable-mmx
    	make
    	make install


ToDo
==========
1. Documentation on how to setup and run on Windows 
2. Web-ize configuration and running PiDoorbell from a GUI
3. Fix bugs
4. Audio notification to visitor when they are detected - welcome message
5. Two-way video/audio
6. PiDoorbell Mobile app 


Distribution structure
==========

1. Main directory with 
	README
	pidoorbell-recognizer-gpio.py 
	send_notifications.py
	sms_auth_info.py - you will have to create this.  See Doc.
	dropbox-uploader.sh
	HC_SRO4.py
	dropbox_token.txt
	Docs/Tutorial
	Docs/*.jpg
	Docs/more stuff to come
	
2. Subdirectories
	dropbox-pidoorbell - stores video/audio clips to upload to Dropbox
	Docs - Additional documentation and tutorial, slides 


Contributors 
==========
All contributors are members of:
CodeChix
http://www.codechix.org/
https://github.com/codechix
https://github.com/rdachere
https://github.com/akkana
https://github.com/deepadhurka
https://github.com/serpilb

Sorted by last name:

Bayraktar, Serpil - serpil@cisco.com
Dachere, Rupa - rupa@codechix.org
Karnad, Deepa - deepa.karnad@gmail.com
Peck, Akkana - akkana@gmail.com