AWS Panorama Developer Guide

.gitignore

@@ -0,0 +1,4 @@
+*.zip
+*.tar.gz
+bucket-name.txt
+out.yml

CODE_OF_CONDUCT.md

@@ -2,3 +2,4 @@
 This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
 For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
 [email protected] with any additional questions or comments.
+

CONTRIBUTING.md

@@ -59,3 +59,4 @@ If you discover a potential security issue in this project we ask that you notif
 See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
 
 We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.
+

LICENSE

@@ -13,3 +13,4 @@ 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.
 
+

README.md

@@ -1,13 +1,10 @@
-## My Project
+## AWS Panorama Developer Guide
 
-TODO: Fill this README out!
+This repository contains the Markdown version of the AWS Panorama Developer Guide and additional resources that you can use to learn about AWS Panorama concepts and features.
 
-Be sure to:
+Table of contents: [index.md](/doc-source/index.md)
 
-* Change the title in this README
-* Edit your repository description on GitHub
+## License Summary
 
-## License
-
-This library is licensed under the MIT-0 License. See the LICENSE file.
+The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the [LICENSE](./LICENSE) file.
 

docs-source/appliance-applications.md

@@ -0,0 +1,13 @@
+# Manage applications on an AWS Panorama Appliance<a name="appliance-applications"></a>
+
+An application is a combination of Lambda functions, models and configuration\. From the appliance management page of the AWS Panorama console, you can modify an application's configuration and deploy published versions to the AWS Panorama Appliance\.
+
+**To manage applications on an AWS Panorama Appliance**
+
+1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\.
+
+1. Choose an appliance\.
+
+1. Choose the **Applications** tab\.
+
+The current applications page shows applications that have been deployed to the appliance\. You can use the options on this screen to remove deployed applications from the appliance\. To monitor deployments, choose **Application operations**\.

docs-source/appliance-buttons.md

@@ -0,0 +1,32 @@
+# AWS Panorama Appliance buttons and lights<a name="appliance-buttons"></a>
+
+The AWS Panorama Appliance has two LED lights above the power button that indicate the device status and network connectivity\.
+
+![\[\]](http://docs.aws.amazon.com/panorama/latest/dev/images/appliance-leds.png)
+
+The LEDs change color and blink to indicate status\. A slow blink is once every three seconds\. A fast blink is once per second\.
+
+**Status LED states**
++ **Fast blinking green** – The appliance is booting up\.
++ **Solid green** – The appliance is operating normally\.
++ **Slow blinking blue** – The appliance is copying configuration files and attempting to register with AWS IoT Greengrass\.
++ **Fast blinking red** – The appliance encountered an error during start up or is overheated\.
++ **Slow blinking orange** – The appliance is restoring the latest software image\.
++ **Fast blinking orange** – The appliance is restoring the factory software image
+
+To reset the device, use the following button combinations\. A short press is 1 second\. A long press is 5 seconds\.
+
+**Reset operations**
++ **Short press power** – Shut down the appliance\.
++ **Short press reset** – Restore the latest software image\.
++ **Long press reset** – Restore the factory software image\.
++ **Short press power and reset** – Start the provisioning sequence\. Copy files from an attached USB drive and register with AWS IoT Greengrass\.
++ **Long press power and reset** – Restore the factory software image and erase all user data\. **Delete configuration files, certificates and applications**\.
+
+The network LED has the following states:
+
+****
++ **Solid green** – An Ethernet cable is connected\.
++ **Blinking green** – The appliance is communicating over the network\.
++ **Solid red** – An Ethernet cable is not connected\.
++ **Solid blue** – An Ethernet cable is not connected, but WiFi is enabled\.

docs-source/appliance-cameras.md

@@ -0,0 +1,51 @@
+# Managing camera streams for an AWS Panorama Appliance<a name="appliance-cameras"></a>
+
+To register video streams as data sources for your application, use the AWS Panorama console\. An application can process multiple streams simultaneously and multiple appliances can connect to the same stream\.
+
+**To add a camera stream**
+
+1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\.
+
+1. Choose an appliance\.
+
+1. Choose **Camera streams**\.
+
+1. Choose **Add camera**\.
+
+1. Choose a connection mode\.
+   + **Automatic** – The AWS Panorama Appliance discovers cameras on the local network\. Choose a camera and then choose a stream to add\. If the camera has multiple streams, repeat the process to add additional streams\.
+   + **Manual** – Enter the IP address of the camera and the RTSP URL of a stream\.
+
+   Both workflows support password\-protected cameras\.
+
+1. Choose **Confirm**\.
+
+**Note**  
+The AWS Panorama Appliance can connect to any camera stream that is routable from the local network it connects to\. To secure your video streams, configure your network to allow only RTSP traffic locally\. For more information, see [Security in AWS Panorama](panorama-security.md)\.
+
+## Supported camera models<a name="appliance-cameras-models"></a>
+
+The AWS Panorama Appliance supports H\.264 video streams from cameras that output RTSP over a local network\. The following camera models have been tested for compatibility with the AWS Panorama Appliance\.
++ [Anpviz](https://anpvizsecurity.com/) – IPC\-B850W\-S\-3X, IPC\-D250W\-S
++ [Axis](https://www.axis.com/) – M3057\-PLVE, M3058\-PLVE, P1448\-LE, P3225\-LV Mk II
++ [LaView](https://www.laviewsecurity.com/) – LV\-PB3040W
++ [Vivotek](https://www.vivotek.com/) – IB9360\-H
++ **WGCC** – Dome PoE 4MP ONVIF
+
+For the appliance's hardware specifications, see [AWS Panorama Appliance Developer Kit specifications](gettingstarted-hardware.md)\.
+
+## Removing a stream<a name="appliance-cameras-remove"></a>
+
+To deregister a video stream, remove it from the appliance's inputs\.
+
+**To remove a camera stream**
+
+1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\.
+
+1. Choose an appliance\.
+
+1. Choose **Camera streams**\.
+
+1. Choose a stream\.
+
+1. Choose **Remove stream**\.

docs-source/appliance-devkit.md

@@ -0,0 +1,66 @@
+# The AWS Panorama Appliance Developer Kit<a name="appliance-devkit"></a>
+
+The AWS Panorama Appliance Developer Kit is a version of the AWS Panorama Appliance hardware that has developer features enabled\. With the AWS Panorama Appliance Developer Kit, you can connect to the appliance over SSH to run commands\.
+
+**Important**  
+The AWS Panorama Appliance Developer Kit is not secured for use on production networks or workloads\. For more information, see [Security in AWS Panorama](panorama-security.md)\.
+
+If you are using the AWS Panorama Appliance Developer Kit for the first time, follow the tutorial at [Using the AWS Panorama Appliance Developer Kit](gettingstarted-devkit.md)\. The tutorial provides an introduction to connecting to the device with SSH, viewing logs, and using Python libraries\.
+
+**Topics**
++ [Connecting with SSH](#appliance-devkit-ssh)
++ [Local storage](#appliance-devkit-storage)
++ [Granting additional permissions](#appliance-devkit-permissions)
++ [Logs](#appliance-devkit-logs)
+
+## Connecting with SSH<a name="appliance-devkit-ssh"></a>
+
+If you configured SSH access when you [set up the appliance](gettingstarted-setup.md), you can connect to it from the command line to view logs, test Python scripts, and inspect the device's configuration\.
+
+To connect to the appliance with SSH, use the `ssh` command with the username and password that you configured during setup\.
+
+```
+$ ssh 10.24.34.0 -l me
+[email protected]'s password:
+```
+
+## Local storage<a name="appliance-devkit-storage"></a>
+
+To store your application code locally on the appliance, use the `/data` directory\. You can use this space to store scripts and other resources\.
+
+**Warning**  
+Do not use the user directory under `/home` for local storage\. This directory is reset when you update your appliance\. Files that you add there are deleted\.
+
+## Granting additional permissions<a name="appliance-devkit-permissions"></a>
+
+The AWS Panorama Appliance Developer Kit has an AWS Identity and Access Management \(IAM\) role that grants it limited permission to access resources in your account\. You create this role, AWSPanoramaGreengrassGroupRole, when you first use the AWS Panorama console\.
+
+By default, the appliance has permission to upload logs to CloudWatch Logs, to post metrics to CloudWatch, and to access objects in buckets that you create for use with AWS Panorama\. You can add permissions to the role to give the appliance and your application code permission to use additional AWS services\.
+
+**To extend the appliance's permissions**
+
+1. Open [the AWSPanoramaGreengrassGroupRole role](https://console.aws.amazon.com/iam/home#/roles/AWSPanoramaGreengrassGroupRole) in the IAM console\.
+
+1. Choose **Attach policies**\.
+
+1. Attach a policy that grants permission to use an AWS service\.
+
+For more information on permissions in AWS Panorama, see [AWS Panorama permissions](panorama-permissions.md)\.
+
+## Logs<a name="appliance-devkit-logs"></a>
+
+After connecting to the appliance with SSH, you can find logs in the following locations\.
+
+****
++ **Application code** – `/data/greengrass/ggc/var/log/user/us-east-1/123456789012/function-name.log`
+
+  Replace the highlighted values with your AWS Region, account ID, and function name\.
++ **AWS IoT Greengrass system** – `/data/greengrass/ggc/var/log/system`
++ **AWS Panorama Appliance** – `/aws/panorama_device/iot-thing-name`
+
+  Log streams include `syslog`, `iot_job_agent`, `mediapipeline`, and a stream for each camera\.
++ **CloudWatch Logs agent** – `/var/log/awslogs.log`
+
+Most of these logs are also sent to CloudWatch Logs\. For more information, see [Monitoring AWS Panorama resources and applications](panorama-monitoring.md)\.
+
+For a tutorial that introduces the AWS Panorama Appliance Developer Kit and debugging, see [Using the AWS Panorama Appliance Developer Kit](gettingstarted-devkit.md)

docs-source/appliance-manage.md

@@ -0,0 +1,44 @@
+# Managing an AWS Panorama Appliance<a name="appliance-manage"></a>
+
+You can use the AWS Panorama console to configure, upgrade or deregister the AWS Panorama Appliance\.
+
+To set up an appliance, follow the instructions in the [getting started tutorial](gettingstarted-setup.md)\. The setup process creates the resources in AWS Panorama that track your appliance and coordinate updates and deployments\.
+
+**Topics**
++ [Upgrade the appliance software](#appliance-manage-software)
++ [Deregister an appliance](#appliance-manage-delete)
+
+## Upgrade the appliance software<a name="appliance-manage-software"></a>
+
+You can view and deploy software updates for the AWS Panorama Appliance in the AWS Panorama console\. Updates can be required or optional\. When a required update is available, the console prompts you to apply it\. You can apply optional updates on the appliance settings page\.
+
+**Important**  
+When you update the appliance software, all data on the device is reset except the `/data` directory\. This directory includes your application data and logs\. You can also use `/data` to store scripts and other files\. For details, see [The AWS Panorama Appliance Developer Kit](appliance-devkit.md)\.
+
+**To upgrade the appliance software**
+
+1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\.
+
+1. Choose an appliance\.
+
+1. Choose **Settings**
+
+1. Under **System software**, choose **Install version**\.
+
+## Deregister an appliance<a name="appliance-manage-delete"></a>
+
+If you are done working with the AWS Panorama Appliance, you can use the AWS Panorama console to deregister it and delete the associated AWS IoT and AWS IoT Greengrass resources\.
+
+**To delete an appliance**
+
+1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\.
+
+1. Choose the appliance\.
+
+1. Choose **Delete**\.
+
+1. Enter the appliance's name and choose **Delete**\.
+
+Data on the appliance is not deleted automatically\. This data includes the appliance certificate, network configuration, camera information, and logs\. To delete this data, reset the appliance to the factory image and state\.
+
+To fully reset the device and delete all data, press both the power button and the reset button for over 5 seconds\. For more information, see [AWS Panorama Appliance buttons and lights](appliance-buttons.md)\.

docs-source/applications-awssdk.md

@@ -0,0 +1,42 @@
+# AWS SDK for Python \(Boto3\)<a name="applications-awssdk"></a>
+
+You can use the AWS SDK for Python \(Boto\) to call AWS services from your application code\. For example, if your model detects something out of the ordinary, you could post metrics to Amazon CloudWatch, send an notification with Amazon SNS, save an image to Amazon S3, or invoke a Lambda function for further processing\. Most AWS services have a public API that you can use with the AWS SDK\.
+
+The appliance does not have permission to access all AWS services by default\. To grant it permission, add the API actions that it uses to the appliance's role \([AWSPanoramaGreengrassGroupRole](permissions-services.md)\)\. You create this role when you first use the AWS Panorama console; it comes with limited permission to use Amazon S3 CloudWatch, and Amazon CloudWatch Logs\.
+
+**Topics**
++ [Using Amazon S3](#applications-awssdk-s3)
++ [Using the AWS IoT message stream](#monitoring-messagestream)
+
+## Using Amazon S3<a name="applications-awssdk-s3"></a>
+
+You can use Amazon S3 to store processing results and other application data\.
+
+```
+import boto3
+s3_client=boto3.client("s3")
+s3_clients3.upload_file(data_file,
+                    s3_bucket_name,
+                    os.path.basename(data_file))
+```
+
+The appliance has permission to access buckets that include `aws-panorama` in the name\. To grant it additional permission, you can modify the appliance's role \([AWSPanoramaGreengrassGroupRole](permissions-services.md)\)\.
+
+## Using the AWS IoT message stream<a name="monitoring-messagestream"></a>
+
+You can monitor an AWS Panorama application by sending application data or message to MQTT message queue and watch the message stream in the AWS IoT console\.
+
+```
+import boto3
+iot_client=boto3.client('iot-data')
+topic = "panorama/panorama_my-appliance_Thing_a01e373b"
+iot_client.publish(topic=topic, payload="my message")
+```
+
+**To monitor an MQTT queue**
+
+1. Open the [AWS IoT console **Test** page](https://console.aws.amazon.com/iot/home?region=us-east-1#/test)\.
+
+1. Paste the "`{topic}/infer`" value into the **Subscription topic** input field\.
+
+1. Choose **Subscribe to topic** to watch the messages published by the `iot_client` from your application code\.