---- SNAP Connect RobotArm demo ----

This example uses SNAP Connect for web browser based remote control of a
robot arm. The hardware in this case is an OWI Robotic Arm Edge, which 
is available from many hobby and toy outlets in kit form for about $50
at the time of this writing (OWI-535).

The hardware modifications to control this robot wirelessly with SNAP are
detailed in the pdf file accompanying this example.  Components used are
a Synapse SN171 protoboard, and the OWI-535-USB interface kit (an additional
$25 item).


What it does
--------------------------
When this example is running, it provides a web interface with the following:
* A realtime plot of sensor data - light-level reading of remote SNAP node
* A stopwatch timer, with start/stop/reset controlled by remote SNAP node.
* Graphical control of grip, wrist, elbow, shoulder, base, and lamp of robot.
* Multi-touch support, for simultaneous operation of all movement axes when
  using a tablet, smartphone, or other device supporting touch events.


Device Scripts
--------------------------
The SNAPpy script loaded on the protoboard (robotArm.py) provides the following
function which can be called over-the-air to control all robot-arm actions:

    def robotPulse(grip, wrist, elbow, shoulder, base, lamp):
        '''Safe means of commanding robot. Pulse values are +-0.1s or None.'''

This function can be used with Portal to test the operation of the robot arm.

Note that this script requires the RESET/GPIO5 button on the SN171 to be in the
GPIO5 position. Otherwise the script will go to sleep in approximately 2 seconds
and never wake up. You can tell the script is "awake and ready to control the arm"
by the rapidly blinking GREEN LED.

With the jumper correctly in the GPIO5 position, the script at powerup will be in
the "awake" state (blinking green). You can press AND HOLD the SWITCH S1 button on
the SN171 for 2 seconds to deliberately put the board to sleep. While the 2 second
countdown is taking place, the YELLOW LED will be blinking instead of the green LED.
Once the unit goes to sleep, neither LED will be blinking. You can wake the board
back up by quickly pressing and releasing the same button.

This "sleeping" capability was implemented in the script to conserve battery power,
since the SN171 Protoboard is likely running from the batteries in the robot arm base.

Script robotArm.py is all you need to demonstrate control of the robot arm from a
web page. However, if you have some extra SNAP Nodes you can implement the "full game".

The following functions can be called over-the-air by remote devices to update the
web-based stopwatch timer and light-level graph. 

    def cycle_timer(self):
        '''RPC from remote SNAP device, typically button-press to start/stop/reset timer'''

    def light_report(self, val):
        '''RPC received from remote SNAP Light Sensor'''

Example scripts implementing these functions are NOT provided. Refer to the SNAP REFERENCE
MANUAL for example scripts that can be used as the basis for these simple scripts.
        
The Game
--------------------------
This example has been used to build a demonstration game with three snap devices:
light sensor, pushbutton, and robot-arm. The devices are arranged so that the 
robot arm can be controlled to push the button (starting the timer) and then moved
to pick up a black material which is used to cover the light-sensor. When the
light-sensor is covered, the timer stops. The object of the game is to achieve the
shortest possible stopwatch time, through mastery of remote-controlling the arm.

Server Code
--------------------------
The main SNAP Connect / Web Server program is robotServer.py.  Edit the serial
port parameters in local_overrides.py to match your bridge connection, and run this
program on your PC. This will provide a web server at http://localhost:8888 which
allows interactive control of the robot arm.

You will find that the SNAP Connect related code in robotServer.py is very similar
to other example applications. It just provides a means to perform RPC calls through
the serially connected bridge.

The web server code is provided by a python package called Tornado.
    http://www.tornadoweb.org/
The core Tornado code (v2.2) is included in the example. To fully understand
this web server you should refer to the online documentation at the above link.

There is not much html in this example - the 'templates/index.html' file defines
the page structure, and it is the javascript code in 'static/main.js' which does
the work of detecting user-input and passing messages between the server and the
page. For realtime messaging we are using WebSockets. This standard asynchronous
protocol is supported by Tornado, and by all modern browsers.

Licensing
-------------------------
The javascript code uses two 3rd party libraries: jQuery, and HighCharts. Please refer
to their respective websites for licensing and updates.

jQuery files are included with this example under the MIT license.
    http://jquery.com/

    Copyright (c) 2011 John Resig, http://jquery.com/

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

HighCharts files are included with this example under the  Creative Commons
Attribution-NonCommercial 3.0 License, EXCLUSIVELY
  "For developing and testing applications using Highcharts"
as specifially allowed by Highsoft Solutions.
For use in commercial applications, a license MUST be purchased from Highsoft.
    http://www.highcharts.com/
    
Tornado (www.tornadoweb.org) is included under the following license: 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

