Initial Commit

.gitignore

@@ -0,0 +1 @@
+*.log

LICENSE

@@ -0,0 +1,174 @@
+Copyright 2016 Microchip Technology Inc. (www.microchip.com)
+
+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.
+
+###############################################################################
+
+Copyright (c) 2014 GitHub Inc.
+
+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.
+
+###############################################################################
+
+Copyright jQuery Foundation and other contributors, https://jquery.org/
+
+This software consists of voluntary contributions made by many
+individuals. For exact contribution history, see the revision history
+available at https://github.com/jquery/jquery
+
+The following license applies to all parts of this software except as
+documented below:
+
+====
+
+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.
+
+====
+
+All files located in the node_modules and external directories are
+externally maintained libraries used by this software which have their
+own licenses; we recommend you read them, as their terms may differ from
+the terms above.
+
+###############################################################################
+
+The bundled package of the AWS SDK for JavaScript is available under the
+Apache License, Version 2.0:
+
+  Copyright 2012-2014 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+  Licensed under the Apache License, Version 2.0 (the "License"). You
+  may not use this file except in compliance with the License. A copy of
+  the License is located at
+
+      http://aws.amazon.com/apache2.0/
+
+  or in the "license" file accompanying this file. This file 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.
+
+This product bundles browserify, which is available under a
+"3-clause BSD" license:
+
+  Copyright Joyent, Inc. and other Node contributors.
+
+  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.
+
+This product bundles crypto-browserify, which is available under
+the MIT license:
+
+  Copyright (c) 2013 Dominic Tarr
+
+  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.
+
+This product bundles MD5, SHA-1, and SHA-256 hashing algorithm components,
+which are available under a BSD license:
+
+  Copyright (c) 1998 - 2009, Paul Johnston & Contributors
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+
+  Redistributions of source code must retain the above copyrightnotice,
+  this list of conditions and the following disclaimer. Redistributions
+  in binary form must reproduce the above copyright notice, this list of
+  conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+  Neither the name of the author nor the names of its contributors may
+  be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+  THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,3 +1,192 @@
-### Insight on Things (IoT) App
+### Microchip Insight on Things Desktop Application
+#### Installation and usage guide
 
-This application will be released by June 2016.
+---
+
+### Introduction
+[AWS IoT](http://aws.amazon.com/iot/) is a service that will allow internet of things (IoT) devices to be easily and securely connected to Amazon Web Services (AWS).  The __Insight on Things__ desktop application has been designed to work with this service via the shadow registers in AWS IoT to control Microchip's IoT demo.
+
+Currently this demo is designed to work with the following demos:
+- [Microchip IoT PIC32MZ based Demos Powered By AWS](https://github.com/MicrochipTech/aws-iot-firmware-pic32mz)
+
+For more information on the current Microchip IoT demos please go to [Microchip's IoT Page](http://www.microchip.com/iot).
+
+---
+
+### Required Tools and Applications
+#### OS Requirements
+We have build and tested the Insight on Things Desktop Application on the following OS's:
+- __OS X:__ 10.11.x
+- __Linux:__ Debian Based - Ubuntu 14.04LTS
+- __Windows:__ Windows 7
+
+#### AWS Tools and Applications
+- You will need an AWS account to use AWS IoT.
+  - For more information how to setup an AWS Account please go to [AWS](http://aws.amazon.com) main page
+  - Please check with your IT or IS department on your company's policies on using cloud computing, or to see if you have a corporate AWS account that should be used.
+
+- To use the AWS IoT services you will need to make use of _AWS Command Line Interface_ (awscli) tool.  For more information on how to install, configure, and use the awscli tool please go to [AWS Command Line Interface User Guide](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
+
+> NOTE: If you are a **Microchip Employee** we have a corporate AWS account that must be used.  To setup your AWS IoT device please go to https://setup.iot.microchip.com for more information
+
+---
+### Setting Up the AWS Command Line Interface
+#### Linux, Unix, and Windows Installations
+Follow the instructions in the [Getting Set Up with the AWS Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) for installations for your operating system.
+
+#### Mac OS X Installation
+This assumes that you have not installed previous version of Python, awscli, or openssl; if you have you will need to uninstall those versions.  You will need to use a version of openssl 1.0.0 or later to connect to AWS IoT services as TLS 1.1 is required.  To do this follow the these steps:
+
+1. Use [Homebrew](http://brew.sh/) to install the latest version of openssl with the following commands in a terminal window.  You will need to force the links so that Python will use the right version of openssl.
+
+  ```
+  brew update
+  brew install openssl
+  brew link --force openssl
+  ```
+- Reinstall Python to use the latest openssl:
+
+  ```
+  brew install python --with-brewed-openssl
+  ```
+- To verify that python was updated run the following command and make sure the version os greater than 1.0.2d
+
+  ```
+  python -c 'import ssl; print ssl.OPENSSL_VERSION'
+  ```
+- Install/upgrade the AWS CLI:
+
+  ```
+  pip install --upgrade awscli
+  ```
+- To verify the version of the AWS CLI tool installed run the following command and look for version 1.10.x or greater:
+
+  ```
+  aws --version
+  ```
+
+---
+### Setting Up the AWS IoT Service for the Insight on Things Application
+
+To setup your AWS IoT service to work with the Insight on Things Desktop Application you will need to work with the awscli that you installed in the previous section.
+
+1. Using the awscli you will need to find the endpoint that will be used for your AWS IoT account.  To do this run the following command in your terminal/command window.
+
+  ```
+  aws iot describe-endpoint
+  ```
+- Create a group that will hold the policy allowing access to the AWS IoT shadow registers
+
+  ```
+  aws iam create-group --group-name iotDemo
+  ```
+- Create the following policy that will allow your Insight on Things Desktop Application to connect to the AWS IoT service and save the file to your computer
+  > NOTE: Make sure you replace `<AWS IoT Region>` and `<AWS Account Number>` with the AWS-IoT region and your AWS account number
+
+  ```
+  }
+    "Version": "2012-10-17",
+    "Statement": [{
+      "Effect": "Allow",
+      "Action": [
+        "iot:GetThingShadow",
+        "iot:UpdateThingShadow"
+        ],
+      "Resource": [
+        "arn:aws:iot:<AWS IoT Region>:<AWS Account Number>:thing/*"
+      ]
+    }]
+  }
+  ```
+- Load the policy to AWS with the following command:
+
+  ```
+  aws iam create-policy --policy-name iotDemoPolicy --policy-document file://<path-to-your-policy-document>
+  ```
+- You will need to attached this policy to a group to allow the users the right to access the AWS IoT shadow registers with the following command:
+  > NOTE: Make sure you replace `<AWS Account Number>` with your AWS account number
+
+  ```
+  aws iam attach-group-policy --policy-arn arn:aws:iam:<AWS Account Number>:aws:policy/iotDemoPolicy --group-name iotDemo
+  ```
+- Next you will need to create a user for the Insight on Things Desktop Application
+
+  ```
+  aws iam create-user --user-name InsightOnThings
+  ```
+- Add the user to the iotDemo group
+
+  ```
+  aws iam add-user-to-group --user-name InsightOnThings --group-name iotDemo
+  ```
+- To allow the Insight on Things Desktop Application to access AWS you will need to download the required key and tokens for this user
+  > NOTE: The output of this command is the only time that you will be able to see this information.  Store in a secure location. If  it  is  lost,  it cannot be recovered, and you must create a new access key.
+
+  ```
+  aws iam create-access-key --user-name InsightOnThings
+  ```
+
+---
+### Insight On Things Desktop Application Installation
+You will need to [download the latest version](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app/releases/latest) of __Insight on Things__ for your operating system.
+
+
+##### Mac OS X Installation
+1. To install on MAC OS X download the 'Insight.dmg' file and double click on the dmg icon. The installer will open as shown below:
+
+  ![Mac install](documents/images/mac_install.png)
+- To install the application drag the Insight app icon to the Applications folder in the install screen.
+
+#### Linux Installation
+The Linux application is designed to run on Debian based platforms, the most popular being Ubuntu or Linux Mint.
+
+1. To install the application download the Insight.deb file
+
+2. Double clicking on the .deb file will open up the default installer
+
+3.  Right clicking on the file will allow you to open the package installer
+
+  ![Linux install](documents/images/linux_install.png)
+4. The application is located in the /opt/ directory. To run the application open a Terminal window and execute the following command:
+
+  ```
+    linux> /opt/insight/Insight
+  ```
+
+#### Windows Installation
+1. To install on Windows download the 'Insight Setup.exe' file and double click on the .exe to start the installer. This application uses a standard installer shown below:
+
+  ![Windows install](documents/images/windows_install.png)
+
+---
+### Running the Demo
+
+1. Start the Insight on Things Desktop Application on your computer.
+- When the application starts it will look for a file name `.insight` in the Users home directory.
+  - This file contains the information that the app will use to access and authenticate you with AWS IoT
+  - If the `.insight` file is not found the application, it will take you to a screen to enter the credentials that you generated in the [Setting Up the AWS IoT Service for the Insight on Things Application](Setting Up the AWS IoT Service for the Insight on Things Application).
+  - Press the `Create New Thing` button to save the credentials into that file.
+  - Bellow is what the Insight on Things Desktop Application will start with if no credential are found.
+
+    ![No credentials found](documents/images/insight_no_credentials.png)
+- If the `.insight` file is found, and has correct credentials in it, the application will default to the data screen and show the current status of the shadow registers.
+
+  ![Credentials found](documents/images/insight_normal_operation.png)
+  - By using one of the demos listed in the [Introduction](Introduction) section you can change data on that device and see it on the Insight on Things Desktop Application
+  - You can also control the demo by change the status of the LED on this application
+- The credentials and the thing that the application is looking at can be changed at any time, by selecting `Thing -> Settings` from the application menu. This will take you to a screen that will load the current credentials and allow them to be updated.
+
+  ![Update Credentials](documents/images/insight_update_credentials.png)
+  - Update any credentials and press the `Update Credentials` button to save the new credentials into the `.insight` file.
+
+---
+### Troubleshooting
+If you are having trouble connecting with AWS IoT and your thing, check to make sure that each of the issues bellow are resolved.
+
+#### Connection Issue
+- Check that you have a valid internet connection on your network/access point.
+- Ensure that port 443 is open on your network/access point.
+- Ensure that your AWS IoT service is setup properly.
+
+#### Credential Issue
+- The credentials are case sensitive.