03 Raspberry Pi Setup.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Smartphone Garage Remote | 03 | Raspberry Pi Setup\n",
    "\n",
    "## Connecting to the Raspberry Pi\n",
    "One of the main benefits of using the Raspberry Pi is working with its Linux distro, Raspbian. Issuing commands to the OS can be done through a remote terminal. This can be accomplished from a working machine via SSH:\n",
    "```\n",
    "ssh pi@192.168.1.21\n",
    "```\n",
    "Additionally, Unix-based systems were designed to easily mount various filesystems into their own structure for easy access. This can be done with another fairly simple command from the working machine:\n",
    "```\n",
    "sshfs pi@192.168.1.21: /home/matthew/mount/pi\n",
    "```\n",
    "\n",
    "## WebIOPi\n",
    "The crux of this project will be accomplished with the versitile [WebIOPi](http://webiopi.trouch.com/). WebIOPi is a web service that runs on the Raspberry Pi and allows control of the GPIO (general purpose input/output) pins on the Pi via HTTP or CoAP. Functionality can be implemented with Python.\n",
    "\n",
    "### WebIOPi config\n",
    "There are two main aspects of WebIOPi that are used for this project. The first is the config file which will setup the HTTP service, link to the Python script, and configure the pins.\n",
    "\n",
    "#### /etc/webiopi/config\n",
    "```\n",
    "[GPIO]\n",
    "# Initialize following GPIOs with given function and optional value\n",
    "# This is used during WebIOPi start process\n",
    "\n",
    "24 = OUT 0  \n",
    "\n",
    "#------------------------------------------------------------------------#\n",
    "\n",
    "[~GPIO]\n",
    "# Reset following GPIOs with given function and optional value\n",
    "# This is used at the end of WebIOPi stop process\n",
    "\n",
    "24 = OUT 0\n",
    "\n",
    "#------------------------------------------------------------------------#\n",
    "\n",
    "[SCRIPTS]\n",
    "# Load custom scripts\n",
    "\n",
    "default = /home/pi/webiopi/default.py\n",
    "\n",
    "#------------------------------------------------------------------------#\n",
    "\n",
    "[HTTP]\n",
    "# HTTP Server configuration\n",
    "\n",
    "enabled     = true\n",
    "port        = 8000\n",
    "passwd-file = /etc/webiopi/passwd\n",
    "prompt      = \"WebIOPi\"\n",
    "\n",
    "#------------------------------------------------------------------------#\n",
    "\n",
    "[COAP]\n",
    "# CoAP Server configuration\n",
    "\n",
    "enabled = false\n",
    "\n",
    "#------------------------------------------------------------------------#\n",
    "\n",
    "[DEVICES]\n",
    "\n",
    "#------------------------------------------------------------------------#\n",
    "\n",
    "[REST]\n",
    "\n",
    "#------------------------------------------------------------------------#\n",
    "\n",
    "[ROUTES]\n",
    "# Custom REST API routes\n",
    "\n",
    "/garage = /GPIO/24/value\n",
    "```\n",
    "\n",
    "First, during startup the config file will set our garage pin (24) to an output state with low voltage (off). At shutdown, the pin will be set to low voltage as well. \n",
    "\n",
    "Next, the script location is provided for the WebIOPi service. The details of this Python script will be detailed in the next section.\n",
    "\n",
    "The HTTP service is then started on our desired port, and with our chosen username and password, as generated with WebIOPi's password generator (run with superuser privileges):\n",
    "```\n",
    "sudo webiopi-passwd\n",
    "```\n",
    "We can also create a custom REST route to our garage pin. REST (aka Representational State Transfer) is the *way* in which HTTP should be used, and part of this methodology is aided with the use of human-readable routes. But as shown below, the Python macro will take care of our access, eliminating the need for this shortcut. Direct access via the REST route was only useful during testing.\n",
    "\n",
    "### Python script and macro\n",
    "The Python scripts used by WebIOPi are Arduino-like in that they can contain *setup*, *loop*, and *destroy* functions that will be run at startup, throughout, and at the end of the system, respectably. But uniquely, macros can be defined as well. Macros are definitions that can be made within the script and then accessed via a particular REST route.\n",
    "\n",
    "#### /home/pi/webiopi/default.py\n",
    "```\n",
    "import webiopi\n",
    "import time\n",
    "gpio = webiopi.GPIO\n",
    "sleep = time.sleep\n",
    "\n",
    "garage_pin  = 24   # set garage pin\n",
    "garage_wait = 0.3  # wait time (s)\n",
    "\n",
    "\"\"\"\n",
    "Arduino-Like script functions\n",
    "\"\"\"\n",
    "# \"setup\" function called at WebIOPi startup\n",
    "def setup():\n",
    "    return\n",
    "\n",
    "# \"loop\" function run repeatedly by WebIOPi\n",
    "def loop():\n",
    "    return\n",
    "\n",
    "# \"destroy\" function called at WebIOPi shutdown\n",
    "def destroy():\n",
    "    return\n",
    "\n",
    "\"\"\"\n",
    "Macros\n",
    "\"\"\"\n",
    "@webiopi.macro\n",
    "def garage():\n",
    "    gpio.digitalWrite(garage_pin, 1)\n",
    "    sleep(garage_wait)\n",
    "    gpio.digitalWrite(garage_pin, 0)\n",
    "    return\n",
    "```\n",
    "In our case, putting our garage logic inside the loop is not ideal. By defining a macro, we can operate our garage remote at any time with a direct POST command. Our macro is fairly simple; the remote is switched on, and after a short amount of time, it is switched off. The macro can be accessed via the REST route,\n",
    "```\n",
    "/macros/garage\n",
    "```\n",
    "\n",
    "## Port Forwarding\n",
    "Within our network, the Raspberry Pi's WebIOPi service can be access through port 8000 and its local IP address. For instance, we can activate our garage macro via,\n",
    "```\n",
    "POST username:password@192.168.1.21:8000/macros/garage\n",
    "```\n",
    "However, it is not always convenient to be on our local network to activate our remote. From outside the house, obtaining a wireless connection can require waiting by the garage door for nearly 30 seconds. To fix this issue, we can fallback to the cellular data network, accessing our Raspberry Pi from outside the local network. \n",
    "\n",
    "To do this, we replace the local IP address of our Pi with the IP address of our house (as can be found from websites such as [this](http://canihazip.com)).  Next, we need to tell our home router to forward incoming traffic on port 8000 to the Pi. The exact method depends on the router software, but most routers allow port forwarding."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python [conda root]",
   "language": "python",
   "name": "conda-root-py"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}