Merge pull request #152 from intel-iot-devkit/feature/python/examples/close-call-reporter

Merge Python Close Call Reporter Example

Author: deadprogram

close-call-reporter/python/LICENSES.md

@@ -0,0 +1,20 @@
+Copyright (c) 2015 - 2016 Intel Corporation.
+
+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.

close-call-reporter/python/README.md

@@ -0,0 +1,191 @@
+# Close Call Reporter in Python*
+
+## Introduction
+
+This Close Call Reporter application is part of a series of how-to Intel® Internet of Things (IoT) code sample exercises using the Intel® IoT Developer Kit, Intel® Edison development platform, cloud platforms, APIs, and other technologies.
+
+From this exercise, developers will learn how to:<br>
+- Connect the Intel® Edison development platform, a computing platform designed for prototyping and producing IoT and wearable computing products.<br>
+- Interface with the Intel® Edison platform IO and sensor repository using MRAA and UPM from the Intel® IoT Developer Kit, a complete hardware and software solution to help developers explore the IoT and implement innovative projects.<br>
+- Store the Close Call Reporter data using Azure Redis Cache\* from Microsoft\* Azure\*, Redis Store\* from IBM\* Bluemix\*, or ElastiCache\* using Redis\* from Amazon Web Services\* (AWS), different cloud services for connecting IoT solutions including data analysis, machine learning, and a variety of productivity tools to simplify the process of connecting your sensors to the cloud and getting your IoT project up and running quickly.
+- Set up a MQTT-based server using IoT Hub from Microsoft\* Azure\*, IoT from IBM\* Bluemix\*, or IoT from Amazon Web Services\* (AWS), different cloud machine to machine messaging services based on the industry standard MQTT protocol.
+
+## What it is
+
+Using an Intel® Edison board, this project lets you create a close call fleet driving reporter that:<br>
+- monitors the Grove* IR Distance Interrupter.<br>
+- monitors the Grove* GPS.<br>
+- keeps track of close calls and logs them using cloud-based data storage.
+
+## How it works
+
+This close call reporter system monitors the direction the IR Distance sensor is pointed to.
+
+It also keeps track of the GPS position of the Intel® Edison board, updating the position frequently to ensure accurate data.
+
+If a close call is detected (that is, the IR Distance sensor is tripped), the Intel® Edison board, if configured, notifies the Intel® IoT Examples Datastore or an MQTT server running in your own Microsoft\* Azure\*, IBM\* Bluemix\*, or AWS account.
+
+## Hardware requirements
+
+Grove* Transportation and Safety Kit, containing:
+
+1. Intel® Edison with an Arduino* breakout board
+2. [Grove\* IR Distance Interrupter](http://iotdk.intel.com/docs/master/upm/node/classes/rfr359f.html)
+3. [Grove\* GPS](http://iotdk.intel.com/docs/master/upm/node/classes/ublox6.html)
+
+DFRobot* Starter Kit for Intel® Edison, containing:
+
+1. Intel® Edison with an Arduino* breakout board
+2. [IR Distance Sensor](http://www.dfrobot.com/index.php?route=product/product&product_id=572)
+3. [GPS](http://iotdk.intel.com/docs/master/upm/node/classes/ublox6.html)
+4. [I/O Expansion Shield](http://www.dfrobot.com/index.php?route=product/product&product_id=1009)
+
+## Software requirements
+
+1. Microsoft\* Azure\*, IBM\* Bluemix\*, or AWS account (optional)
+
+### How to set up
+
+To begin, clone the **How-To Intel IoT Code Samples** repository with Git* on your computer as follows:
+
+    $ git clone https://github.com/intel-iot-devkit/how-to-code-samples.git
+
+To download a .zip file, in your web browser go to <a href="https://github.com/intel-iot-devkit/how-to-code-samples">https://github.com/intel-iot-devkit/how-to-code-samples</a> and click the **Download ZIP** button at the lower right. Once the .zip file is downloaded, uncompress it, and then use the files in the directory for this example.
+
+### Connecting the Grove\* sensors
+
+![](./../../images/js/access-control.jpg)
+
+You need to have a Grove\* Shield connected to an Arduino\*-compatible breakout board to plug all the Grove devices into the Grove\* Shield. Make sure you have the tiny VCC switch on the Grove\* Shield set to **5V**.
+
+1. Plug one end of a Grove\* cable into the Grove\* PIR Motion Sensor, and connect the other end to the D4 port on the Grove\* Shield.
+
+2. Plug one end of a Grove\* cable into the Grove RGB LCD, and connect the other end to any of the I2C ports on the Grove\* Shield.
+
+### Connecting the DFRobot\* sensors
+
+![](./../../images/js/access-control-dfrobot.jpg)
+
+You need to have a LCD Display Shield connected to an Arduino\*-compatible breakout board to plug all the DFRobot\* devices into the LCD Display Shield.
+
+1. Plug one end of a DFRobot\* cable into the PIR (Motion) Sensor, and connect the other end to the A2 port on the LCD Display Shield.
+
+### Intel® Edison board setup
+
+If you're running this code on your Intel® Edison board, you need to install some dependencies by establishing an SSH session to the Edison and run the commands in the sections below.
+
+#### Update the opkg repo
+
+To add the Intel opkg repository:
+
+    $ echo "src mraa-upm http://iotdk.intel.com/repos/3.5/intelgalactic/opkg/i586" > /etc/opkg/mraa-upm.conf
+    $ opkg update
+
+You'll only need to perform this step once.
+
+#### Git
+
+To install Git\* on the Intel® Edison board (if you don’t have it yet):
+
+    $ opkg update
+    $ opkg install git
+
+#### MRAA and UPM Dependencies
+
+To install the latest versions of the MRAA\* and UPM\* libraries:
+
+    $ opkg update
+    $ opkg install mraa
+    $ opkg install upm
+
+#### Python Package Manager (pip)
+
+To install the Python\* package manager needed to install and run the example:
+
+    $ pip install --upgrade pip setuptools
+
+
+#### Install the example
+
+Once all dependencies are installed you can install the example itself with the following command:
+
+    $ pip install --src ~/python/examples/ -e "git+https://github.com/intel-iot-devkit/how-to-code-samples.git#egg=iot_close_call_reporter&subdirectory=close-call-reporter/python"
+
+The `pip` command will install required Python dependencies, save the source code for the example in `~/python/examples/iot_close_call_reporter/` and link the package to the global Python `site-packages` folder.
+
+### Intel® IoT Gateway setup
+
+You can run this example using an Intel® IoT Gateway connected to an Arduino\*/Genuino\* 101.
+
+Make sure your Intel® IoT Gateway is setup, by following the directions on the web site here:
+
+https://software.intel.com/en-us/node/633284
+
+You must install the Intel® XDK on the Intel® IoT Gateway, by following the directions on the above link, under the section "Connecting to the Intel® XDK".
+
+The Arduino\*/Genuino\* 101 needs to have the Firmata\* firmware installed. If you have IMRAA installed on your gateway, this will be done automatically. Otherwise, install the StandardFirmata or ConfigurableFirmata sketch manully on to your Arduino\*/Genuino\* 101.
+
+You will also need to configure the `config.json` in the example to use the Arduino\*/Genuino\* 101. See the section "Configuring the example" below.
+
+### Data store server setup
+
+Optionally, you can store the data generated by this sample program in a back-end database deployed using Microsoft\* Azure\*, IBM\* Bluemix\*, or AWS, along with Node.js\*, and a Redis\* data store.
+
+For information on how to set up your own cloud data server, go to:
+
+[https://github.com/intel-iot-devkit/intel-iot-examples-datastore](https://github.com/intel-iot-devkit/intel-iot-examples-datastore)
+
+### MQTT server setup
+
+You can also optionally store the data generated by this sample program using MQTT, a machine-to-machine messaging server. You can use MQTT to connect to Microsoft\* Azure\*, IBM\* Bluemix\*, or AWS.
+
+For information on how to connect to your own cloud MQTT messaging server, go to:
+
+[https://github.com/intel-iot-devkit/intel-iot-examples-mqtt](https://github.com/intel-iot-devkit/intel-iot-examples-mqtt)
+
+## Configuring the example
+
+When the example is installed through `pip` the `config.json` file that holds the configuration for the example lives in `~/python/examples/iot_close_call_reporter/close-call-reporter/python/iot_close_call_reporter/config.json`.
+
+To configure the example for the Grove* kit, just leave the `kit` key in the `config.json` set to `grove`. To configure the example for the DFRobot* kit, change the `kit` key in the `config.json` to `dfrobot` as follows:
+
+```JSON
+{
+  "kit": "dfrobot"
+}
+```
+
+To configure the example for the optional Microsoft\* Azure\*, IBM\* Bluemix\*, or AWS data store, add the `SERVER` and `AUTH_TOKEN` keys in the `config.json` file below the "CODE" key as follows:
+
+```JSON
+{
+  "kit": "grove",
+  "SERVER": "http://intel-examples.azurewebsites.net/logger/access-control",
+  "AUTH_TOKEN": "s3cr3t"
+}
+```
+
+For information on how to configure the example for the optional Microsoft\* Azure\*, IBM\* Bluemix\*, or AWS MQTT messaging server, go to:
+
+[https://github.com/intel-iot-devkit/intel-iot-examples-mqtt/](https://github.com/intel-iot-devkit/intel-iot-examples-mqtt/)
+
+## Running the program manually
+
+Once the example is installed through `pip` you can run the program by running the following command in an SSH session to the board:
+
+    $ python -m iot_close_call_reporter
+
+### Determining the Intel® Edison board's IP address
+
+You can determine what IP address the Intel® Edison board is connected to by running the following command:
+
+    ip addr show | grep wlan
+
+You will see the output similar to the following:
+
+    3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast qlen 1000
+        inet 192.168.1.13/24 brd 192.168.1.255 scope global wlan0
+
+The IP address is shown next to `inet`. In the example above, the IP address is `192.168.1.13`.
+
+IMPORTANT NOTICE: This software is sample software. It is not designed or intended for use in any medical, life-saving or life-sustaining systems, transportation systems, nuclear systems, or for any other mission-critical application in which the failure of the system could lead to critical injury or death. The software may not be fully tested and may contain bugs or errors; it may not be intended or suitable for commercial release. No regulatory approvals for the software have been obtained, and therefore software may not be certified for use in certain countries or environments.

close-call-reporter/python/iot_close_call_reporter/__init__.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2015 - 2016 Intel Corporation.
+#
+# 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.
+
+from __future__ import print_function, division
+from time import sleep
+from signal import SIGINT, signal
+from atexit import register as register_exit
+from .runner import Runner
+
+def main():
+
+    """
+    Start main function.
+    """
+
+    runner = Runner()
+    print("Running {0} example.".format(runner.project_name))
+
+    def signal_handler(signum, frame):
+        raise SystemExit
+
+    def exit_handler():
+        print("exiting")
+        exit(0)
+
+    register_exit(exit_handler)
+    signal(SIGINT, signal_handler)
+
+    try:
+        signal.pause()
+    except AttributeError:
+        while True:
+            sleep(0.5)
+
+if __name__ == "__main__":
+    main()

close-call-reporter/python/iot_close_call_reporter/__main__.py

@@ -0,0 +1,3 @@
+{
+    "kit": "grove"
+}

close-call-reporter/python/iot_close_call_reporter/config.json

@@ -0,0 +1,93 @@
+# Copyright (c) 2015 - 2016 Intel Corporation.
+#
+# 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.
+
+from collections import namedtuple
+from pkg_resources import resource_stream
+from simplejson import load as load_json
+
+# hardware platform
+HardwareConfig = namedtuple("HardwareConfig", "kit platform")
+
+KIT = "kit"
+PLATFORM = "PLATFORM"
+
+Kits = namedtuple("Kits", "grove dfrobot")
+KNOWN_KITS = Kits(
+    grove="grove",
+    dfrobot="dfrobot"
+)
+
+Platforms = namedtuple("Platforms", "firmata")
+KNOWN_PLATFORMS = Platforms(
+    firmata="firmata"
+)
+
+# app specific
+
+# MQTT server
+MqttConfig = namedtuple("MqttConfig", "server port client_id username password cert key topic")
+
+MQTT_SERVER = "MQTT_SERVER"
+MQTT_PORT = "MQTT_PORT"
+MQTT_CLIENTID = "MQTT_CLIENTID"
+MQTT_USERNAME = "MQTT_USERNAME"
+MQTT_PASSWORD = "MQTT_PASSWORD"
+MQTT_CERT = "MQTT_CERT"
+MQTT_KEY = "MQTT_KEY"
+MQTT_TOPIC = "MQTT_TOPIC"
+
+# remote data store
+DataStoreConfig = namedtuple("DataStoreConfig", "server auth_token")
+
+SERVER = "SERVER"
+AUTH_TOKEN = "AUTH_TOKEN"
+
+# Load configuration data from `project/config.json` file.
+# Edit this file to change to correct values for your configuration
+
+RESOURCE_PACKAGE = __name__
+RESOURCE_PATH = "config.json"
+
+
+with resource_stream(RESOURCE_PACKAGE, RESOURCE_PATH) as data:
+
+    RAW_CONFIG = load_json(data)
+
+    HARDWARE_CONFIG = HardwareConfig(
+        kit=RAW_CONFIG.get(KIT, KNOWN_KITS.grove),
+        platform=RAW_CONFIG.get(PLATFORM)
+    )
+
+    MQTT_CONFIG = MqttConfig(
+        server=RAW_CONFIG.get(MQTT_SERVER),
+        port=RAW_CONFIG.get(MQTT_PORT),
+        client_id=RAW_CONFIG.get(MQTT_CLIENTID),
+        username=RAW_CONFIG.get(MQTT_USERNAME),
+        password=RAW_CONFIG.get(MQTT_PORT),
+        cert=RAW_CONFIG.get(MQTT_CERT),
+        key=RAW_CONFIG.get(MQTT_KEY),
+        topic=RAW_CONFIG.get(MQTT_TOPIC)
+    ) if {MQTT_SERVER, MQTT_CLIENTID, MQTT_TOPIC} <= set(RAW_CONFIG) else None
+
+    DATA_STORE_CONFIG = DataStoreConfig(
+        server=RAW_CONFIG.get(SERVER),
+        auth_token=RAW_CONFIG.get(AUTH_TOKEN)
+    ) if {SERVER, AUTH_TOKEN} <= set(RAW_CONFIG) else None