diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c932dab --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +*.zip +*.tar.gz +bucket-name.txt +out.yml diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 5b627cf..8263783 100644 --- a/CODE_OF_CONDUCT.md +++ b/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 opensource-codeofconduct@amazon.com with any additional questions or comments. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 914e074..25f11e0 100644 --- a/CONTRIBUTING.md +++ b/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. + diff --git a/LICENSE b/LICENSE index 1bb4f21..c1855eb 100644 --- a/LICENSE +++ b/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. + diff --git a/README.md b/README.md index 316e644..8f7e393 100644 --- a/README.md +++ b/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. diff --git a/docs-source/appliance-applications.md b/docs-source/appliance-applications.md new file mode 100644 index 0000000..69ffa89 --- /dev/null +++ b/docs-source/appliance-applications.md @@ -0,0 +1,13 @@ +# Manage applications on an AWS Panorama Appliance + +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**\. \ No newline at end of file diff --git a/docs-source/appliance-buttons.md b/docs-source/appliance-buttons.md new file mode 100644 index 0000000..c6f7ec4 --- /dev/null +++ b/docs-source/appliance-buttons.md @@ -0,0 +1,32 @@ +# AWS Panorama Appliance buttons and lights + +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\. \ No newline at end of file diff --git a/docs-source/appliance-cameras.md b/docs-source/appliance-cameras.md new file mode 100644 index 0000000..f2f4d24 --- /dev/null +++ b/docs-source/appliance-cameras.md @@ -0,0 +1,51 @@ +# Managing camera streams for an AWS Panorama Appliance + +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 + +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 + +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**\. \ No newline at end of file diff --git a/docs-source/appliance-devkit.md b/docs-source/appliance-devkit.md new file mode 100644 index 0000000..cc1c9de --- /dev/null +++ b/docs-source/appliance-devkit.md @@ -0,0 +1,66 @@ +# The AWS Panorama Appliance Developer Kit + +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 + +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 +me@10.24.34.0's password: +``` + +## Local storage + +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 + +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 + +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) \ No newline at end of file diff --git a/docs-source/appliance-manage.md b/docs-source/appliance-manage.md new file mode 100644 index 0000000..21b0cb9 --- /dev/null +++ b/docs-source/appliance-manage.md @@ -0,0 +1,44 @@ +# Managing an AWS Panorama Appliance + +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 + +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 + +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)\. \ No newline at end of file diff --git a/docs-source/applications-awssdk.md b/docs-source/applications-awssdk.md new file mode 100644 index 0000000..c313cda --- /dev/null +++ b/docs-source/applications-awssdk.md @@ -0,0 +1,42 @@ +# AWS SDK for Python \(Boto3\) + +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 + +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 + +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\. \ No newline at end of file diff --git a/docs-source/applications-code.md b/docs-source/applications-code.md new file mode 100644 index 0000000..984fd81 --- /dev/null +++ b/docs-source/applications-code.md @@ -0,0 +1,132 @@ +# Authoring application code + +Your application's code uses the AWS Panorama Application SDK to load the model, run inference, and output results\. You can also use the AWS SDK for Python \(Boto3\) and common machine learning and computer vision libraries like NumPy and OpenCV\. + +AWS Panorama use AWS Lambda and AWS IoT Greengrass to manage and deploy application code\. In Lambda, you [create a Python 3\.7 function](gettingstarted-deploy.md) and publish a version\. Your application uses the function version as its code\. When you deploy an application, AWS Panorama uses AWS IoT Greengrass to deploy the code to the AWS Panorama Appliance with the application's model\. You only use Lambda to store the code, not to run it\. + +The AWS Panorama Application SDK is a Python library that is available in the runtime environment on the AWS Panorama Appliance\. The SDK defines a base class for applications and provides methods for loading a model and using it to process images\. + +**Topics** ++ [Using the base class](#applications-code-base) ++ [Defining inputs and outputs](#applications-code-parameters) ++ [Loading a model](#applications-code-model) ++ [Processing frames](#applications-code-frames) + +## Using the base class + +To create an application class, declare `panoramasdk.base` as the parent class and define the following methods\. + +**** ++ `interface` – Returns a dictionary that defines the class's parameters, input type, and output type ++ `init` – Creates resources that are reused, such as the application's model and AWS SDK clients ++ `entry` – Processes a frame of video from one or more camera streams ++ `main` – Instantiates the class and calls `run()` on it + +The following code shows the basic outline of an application class\. + +**Example my\_application\.py – Class methods** + +``` +import panoramasdk + +class my_application(panoramasdk.base): + + def interface(self): + ... + + def init(self, parameters, inputs, outputs): + ... + + def entry(self, inputs, outputs): + ... + +def main(): + my_application().run() + +main() +``` + +The `run` method is part of the parent class\. It tells the AWS Panorama Application SDK that the application is ready to process video streams\. + +## Defining inputs and outputs + +The `interface` method returns an object that defines the application's parameters, inputs, and outputs\. + +``` + def interface(self): + return { + "parameters": + ( + ("model", "model_name", "Name of the model in AWS Panorama", "aws-panorama-sample-model"), + ), + "inputs": + ( + ("media[]", "video_in", "Camera input stream"), + ), + "outputs": + ( + ("media[video_in]", "video_out", "Camera output stream"), + ) + } +``` + +The `media` array under `inputs` represents input from cameras connected to the appliance\. The application SDK fills this array with frames of video \(one for each stream\) and passes it to the [entry method](#applications-code-frames)\. Similarly, the `outputs` object provides a place to write an output image after processing the input\. + +The `parameters` object defines the application's runtime configuration\. In the preceding example, the `model_name` parameter has type `model` and its value is `aws-panorama-sample-model`\. This value is available by referencing `parameters.model_name`\. To avoid hardcoding names and numbers in your application logic, define them in the interface\. + +Parameters can have the following types\. + +**** ++ `media` – A frame of video ++ `model` – A computer vision model ++ `rect` – A rectangle of \(x0, y0, x1, y1\) ++ `string` – A string ++ `uint32` – A 4 byte, unsigned integer ++ `int` – An integer ++ `float` – A floating point value ++ `byte` – A byte ++ `bool` – `True` or `False` + +## Loading a model + +In the `init` method, load the application's model and create other reusable resources, such as AWS SDK clients\. + +``` + def init(self, parameters, inputs, outputs): + try: + print("Loading model: " + parameters.model_name) + self.model = panoramasdk.model() + self.model.open(parameters.model_name, 1)] + return True + + except Exception as e: + print("Exception: {}".format(e)) + return False +``` + +## Processing frames + +The entry method processes an array of frames from one or more video streams\. The input is an array of `media` objects that represent frames of video\. If the application is connected to one camera stream, `inputs.video_in` has only one object\. + +The following example shows an application getting a frame from each attached camera stream, calling a local `preprocess` method to resize and normalize it, and processing the result with a model\. + +``` + def entry(self, inputs, outputs): + + for i in range(len(inputs.video_in)): + frame = inputs.video_in[i] + frame.add_label('AWS Panorama', 0.8, 0.05) + frame_image = frame.image + + # Prepare the image and run inference + normalized_image = self.preprocess(frame_image) + self.model.batch(0, normalized_image) + self.model.flush() + resultBatchSet = self.model.get_result() + ... + + self.model.release_result(resultBatchSet) + outputs.video_out[i] = frame + + return True +``` \ No newline at end of file diff --git a/docs-source/applications-manage.md b/docs-source/applications-manage.md new file mode 100644 index 0000000..92de177 --- /dev/null +++ b/docs-source/applications-manage.md @@ -0,0 +1,66 @@ +# Managing applications and application versions in AWS Panorama + +Use the AWS Panorama console to manage applications and application versions\. An *application* is a computer vision program that runs on the AWS Panorama Appliance\. *Application versions* are immutable snapshots of an application's configuration\. + +To create an application, you need an AWS Lambda function and a computer vision model that is stored in Amazon SageMaker or Amazon Simple Storage Service \(Amazon S3\)\. The application code is a Python script that uses the AWS Panorama Application SDK to process inputs, run inference, and output video\. If you have not created an application yet, see [Getting started with AWS Panorama](panorama-gettingstarted.md) for a walkthrough\. + +**Topics** ++ [Deploy an application](#applications-manage-deploy) ++ [Update or copy an application](#applications-manage-clone) ++ [Delete versions and applications](#applications-manage-delete) + +## Deploy an application + +To deploy an application, use the AWS Panorama console\. During the deployment process, you'll choose which camera streams to pass to the application code, and whether to send the output to a display\. + +**To deploy an application** + +1. Open the AWS Panorama console [Applications page](https://console.aws.amazon.com/panorama/home#applications)\. + +1. Choose an application\. + +1. \(Optional\) To deploy a previous version of the application, choose a **Version**\. + +1. Choose **Deploy**\. + +1. Follow the instructions to deploy the application version\. + +The deployment process takes a few minutes\. The appliance's output can be blank for an extended period while the application starts\. If you encounter an error, see [Troubleshooting](panorama-troubleshooting.md)\. + +## Update or copy an application + +To update an application or create a copy of it, use the **Clone** option\. Previous versions of applications are saved until you delete them\. When you clone an application, you can update its function or models\. + +**To clone an application** + +1. Open the AWS Panorama console [Applications page](https://console.aws.amazon.com/panorama/home#applications)\. + +1. Choose an application\. + +1. Choose **Clone**\. + +1. Follow the instructions to create a new version or application\. + +## Delete versions and applications + +To clean up unused application versions, delete them\. When you delete an application version, AWS Panorama removes it from connected appliances\. If an appliance is offline when its application is deleted, you can [remove it from the appliance](appliance-applications.md) after it reconnects\. + +**To delete an application version** + +1. Open the AWS Panorama console [Applications page](https://console.aws.amazon.com/panorama/home#applications)\. + +1. Choose an application\. + +1. Under **Version**, choose a version\. + +1. Choose **Delete**\. + +An application must have at least one version\. To remove all versions, delete the application\. + +**To delete an application** + +1. Open the AWS Panorama console [Applications page](https://console.aws.amazon.com/panorama/home#applications)\. + +1. Choose an application\. + +1. Choose **Delete application**\. \ No newline at end of file diff --git a/docs-source/applications-models.md b/docs-source/applications-models.md new file mode 100644 index 0000000..355552b --- /dev/null +++ b/docs-source/applications-models.md @@ -0,0 +1,13 @@ +# Computer vision models + +A computer vision model is a software program that is trained to detect objects in images\. A model learns to recognize a set of objects by analyzing images of those objects\. It takes an image as input and outputs information about objects that it detects\. AWS Panorama supports computer vision models built with PyTorch, Apache MXNet, and TensorFlow\. + +**Note** +For a list of models that have been tested with AWS Panorama, see [Model compatibility](https://github.com/awsdocs/aws-panorama-developer-guide/blob/main/resources/model-compatibility.md)\. + +You can use sample models or build your own\. A model can detect multiple objects in an image, and each result can have multiple outputs, such as the name of a class, a confidence rating, and a bounding box\. You can train a model outside of AWS and store it in Amazon Simple Storage Service \(Amazon S3\), or train it in Amazon SageMaker\. + +**Important** +Whether you import a model from a SageMaker training job or directly from Amazon S3, the Amazon S3 bucket where the model is stored must contain `aws-panorama` in the name\. + +On the appliance, the model files are stored in a folder named after the model resource that you configured in the AWS Panorama console\. The application code uses the directory name to reference the model and load it with the AWS Panorama Application SDK\. \ No newline at end of file diff --git a/docs-source/applications-overlays.md b/docs-source/applications-overlays.md new file mode 100644 index 0000000..f81a60e --- /dev/null +++ b/docs-source/applications-overlays.md @@ -0,0 +1,34 @@ +# Adding text and boxes to output video + +With the AWS Panorama SDK, you can output a video stream to a display\. The video can include text and boxes that show output from model, the current state of the application, or other data\. + +Each object in the `video_in` array is an image from a camera stream that is connected to the appliance\. The type of this object is `panoramasdk.media`\. It has methods to add text and rectangular boxes onto the image, which you can then assign to the `video_out` array\. + +In the following example, the sample application overlays the number of people in frame, and draws a box around each\. It gets the coordinates of the box from the model, which outputs the location of each result, in addition to the class and confidence\. + +**Example lambda\_function\.py – Bounding boxes and text** + +``` + def entry(self, inputs, outputs): + for i in range(len(inputs.video_in)): + stream = inputs.video_in[i] + person_image = stream.image + ... + # Draw bounding boxes on output image + if self.number_people > 0: + for index in person_indices: + + left = np.clip(rect_data[index][0] / np.float(HEIGHT), 0, 1) + top = np.clip(rect_data[index][1] / np.float(WIDTH), 0, 1) + right = np.clip(rect_data[index][2] / np.float(HEIGHT), 0, 1) + bottom = np.clip(rect_data[index][3] / np.float(WIDTH), 0, 1) + + stream.add_rect(left, top, right, bottom) + stream.add_label(str(prob_data[index][0]), right, bottom) + # Add text + stream.add_label('Number of People : {}'.format(self.number_people), 0.8, 0.05) + ... + outputs.video_out[i] = stream +``` + +where \(`x_coordinate=0.1, y_coordinate=0.1`\) means the top\-left corner of the string is placed 10% of the width and hight away from the top\-left corner of the image frame\. If, for example, \(`x_coordinate=1.0, y_coordinate=1.0`\), the top\-left corner of the message label coincides with the bottom\-right corner of the image frame\. In this case, the added message label will become invisible\. \ No newline at end of file diff --git a/docs-source/applications-panoramasdk.md b/docs-source/applications-panoramasdk.md new file mode 100644 index 0000000..0c79149 --- /dev/null +++ b/docs-source/applications-panoramasdk.md @@ -0,0 +1,114 @@ +# The AWS Panorama Application SDK + +The AWS Panorama Application SDK is a Python library for developing AWS Panorama applications\. In your [application code](applications-code.md), you use the AWS Panorama Application SDK to load a computer vision model, run inference, and output video to a monitor\. + +**Note** +To ensure that you have access to the latest functionality of the AWS Panorama Application SDK, [upgrade the appliance software](appliance-manage.md#appliance-manage-software)\. + +You can connect to the AWS Panorama Appliance Developer Kit with SSH to interact with the AWS Panorama Application SDK\. With a Python interpreter, you can load the AWS Panorama Application SDK and verify its behavior\. + +``` +$ python3 +Python 3.7.5 + +>>> import panoramasdk +>>> help(panoramasdk) + + CLASSES + builtins.list(builtins.object) + port + builtins.object + base + batch + batch_set + ... +``` + +For an introduction to using the AWS Panorama Appliance Developer Kit for development, see [Using the AWS Panorama Appliance Developer Kit](gettingstarted-devkit.md)\. + +**Topics** ++ [base](#applications-sdk-base) ++ [model](#applications-sdk-model) ++ [input\_array](#applications-sdk-input) ++ [output\_array](#applications-sdk-output) ++ [batch\_set](#applications-sdk-base-set) ++ [batch](#applications-sdk-batch) ++ [media](#applications-sdk-media) + +## base + +The base class for AWS Panorama application\. Your application code is contained in a class that inherits from `panoramasdk.base`\. + +For an introduction to defining an application class, see [Authoring application code](applications-code.md)\. + +## model + +The `model` class represents a computer vision model\. When you create an application in the AWS Panorama console, you import a model and give it a name\. AWS Panorama includes this model with your application code when you deploy the application to an appliance\. + +**Methods** ++ `panoramasdk.model()` – Creates a model ++ `model.open(name)` – Opens a model by name\. Use the name that you entered when you imported the model in the AWS Panorama console\. ++ `model.get_input(index)` – Gets details about an input for a model\. To distinguish between multiple inputs, specify a numerical index\. Returns a `panoramasdk.input_array` ++ `model.get_output(index)` – Gets details about an output for a model\. To distinguish between multiple outputs, specify a numerical index\. Returns a `panoramasdk.output_array` ++ `model.get_batch_size()` – Gets the input batch size for the model \(an integer\)\. ++ `model.get_input_count()` – Gets the number of inputs that the model requires \(an integer\)\. ++ `model.get_output_count()` – Gets the number of outputs that the model produces \(an integer\)\. ++ `model.get_input_names()` – Gets the names of inputs that the model requires \(a tuple of strings\)\. ++ `model.get_output_names()` – Gets the names of outputs that the model produces \(a tuple of strings\)\. ++ `model.batch(input_index, input_data)` – Sends an array of data \(a numpy array\) to an input \(by index\) for inference\. ++ `model.flush()` – Runs inference with the provided batch input\. ++ `model.get_result()` – Gets inference results \(a `panoramasdk.batch_set`\)\. ++ `model.release_result(batch_set)` – Deletes an inference result after the result has been processed\. ++ `model.finish()` – Stops the model's inference thread to clean up resources\. + +For an introduction to running inference with a model, see [Loading a model](applications-code.md#applications-code-model)\. + +## input\_array + +Represents the input for a model\. + +**Methods** ++ `input_array.get_index()` – Gets the index of the input\. ++ `input_array.get_name()` – Gets the name of the input\. ++ `input_array.get_type()` – Gets the type of the input\. ++ `input_array.get_dims()` – Gets the shape of the input\. ++ `input_array.get_size()` – Gets the size of the input data\. ++ `input_array.get_four_cc()` – Gets the input data's four character code, such as `RGBA` or `BGR3`\. ++ `input_array.get_range()` – Gets the valid range for values in the input \(a tuple of integers\)\. For example, `(0,255)`\. + +## output\_array + +Represents an output for a model\. + +**Methods** ++ `output_array.get_index()` – Gets the index of the output\. ++ `output_array.get_name()` – Gets the name of the output\. ++ `output_array.get_type()` – Gets the type of the output\. ++ `output_array.get_dims()` – Gets the shape of the output\. ++ `output_array.get_size()` – Gets the size of the output data\. + +## batch\_set + +A set of `panoramasdk.batch` objects, one for each output of a model\. + +**Methods** ++ `output_array.size()` – The number of outputs\. ++ `output_array.get(index)` – Gets the batch of results for an output by index\. + +## batch + +A batch of results for a model output, retrieved from a `panoramasdk.batch_set`\. + +**Methods** ++ `batch.get(index, destination)` – Gets an output from a batch and writes it to a destination \(a numpy array\)\. + +## media + +A frame of video from a camera stream\. + +**Methods** ++ `media.image()` – Gets the frame's image data \(a numpy array\)\. ++ `media.add_rect(rect)` – Draws a rectangle around an object\. The input is a tuple of 4 floating point values: left, right, top, bottom\. ++ `media.add_label(text, left_pos, top_pos)` – Adds text to the image\. The input is a string and two floats: a horizontal offset and vertical offset\. ++ `media.stream_uri()` – Gets the URI of the camera stream that provided the frame\. ++ `media.time_stamp()` – Gets the timestamp of the image frame in both seconds and milliseconds \(a tuple of 2 numbers\)\. \ No newline at end of file diff --git a/docs-source/gettingstarted-code.md b/docs-source/gettingstarted-code.md new file mode 100644 index 0000000..4cee148 --- /dev/null +++ b/docs-source/gettingstarted-code.md @@ -0,0 +1,158 @@ +# Sample application code + +The following example shows a Python function that processes video feeds from one or more camera streams \(`video_in`\)\. It loops over frames of video, detects people, and outputs the original video with an overlay that includes the number of people detected, and bounding boxes around each person\. + +**Example application code – People counter** + +``` +import panoramasdk +import cv2 +import numpy as np +import boto3 + +HEIGHT = 512 +WIDTH = 512 + +class people_counter(panoramasdk.base): + + def interface(self): + return { + "parameters": + ( + ("float", "threshold", "Minimum confidence for display", 0.10), + ("model", "people_counter", "Name of the model in AWS Panorama", "aws-panorama-sample-model"), + ("int", "batch_size", "Model batch size", 1), + ("float", "person_index", "The index of the person class in the model's dataset", 14), + ), + "inputs": + ( + ("media[]", "video_in", "Camera input stream"), + ), + "outputs": + ( + ("media[video_in]", "video_out", "Camera output stream"), + ) + } + + + def init(self, parameters, inputs, outputs): + try: + self.threshold = parameters.threshold + self.person_index = parameters.person_index + self.threshold = parameters.threshold + self.frame_num = 0 + self.number_people = 0 + self.colours = np.random.rand(32, 3) + + print("Loading model: " + parameters.people_counter) + self.model = panoramasdk.model() + self.model.open(parameters.people_counter, 1) + + print("Creating input and output arrays") + class_info = self.model.get_output(0) + prob_info = self.model.get_output(1) + rect_info = self.model.get_output(2) + + self.class_array = np.empty(class_info.get_dims(), dtype=class_info.get_type()) + self.prob_array = np.empty(prob_info.get_dims(), dtype=prob_info.get_type()) + self.rect_array = np.empty(rect_info.get_dims(), dtype=rect_info.get_type()) + + print("Initialization complete") + return True + + except Exception as e: + print("Exception: {}".format(e)) + return False + + def preprocess(self, img): + resized = cv2.resize(img, (HEIGHT, WIDTH)) + mean = [0.485, 0.456, 0.406] + std = [0.229, 0.224, 0.225] + + img = resized.astype(np.float32) / 255. + img_a = img[:, :, 0] + img_b = img[:, :, 1] + img_c = img[:, :, 2] + + # Normalize data in each channel + img_a = (img_a - mean[0]) / std[0] + img_b = (img_b - mean[1]) / std[1] + img_c = (img_c - mean[2]) / std[2] + + # Put the channels back together + x1 = [[[], [], []]] + x1[0][0] = img_a + x1[0][1] = img_b + x1[0][2] = img_c + + x1 = np.asarray(x1) + return x1 + + def get_number_persons(self, class_data, prob_data): + # Filter out results beneath confidence threshold + person_indices = [i for i in range(len(class_data)) if int(class_data[i]) == self.person_index] + prob_person_indices = [i for i in person_indices if prob_data[i] >= self.threshold] + return prob_person_indices + + def entry(self, inputs, outputs): + self.frame_num += 1 + + for i in range(len(inputs.video_in)): + stream = inputs.video_in[i] + person_image = stream.image + stream.add_label('People detected: {}'.format(self.number_people), 0.8, 0.05) + + # Prepare the image and run inference + x1 = self.preprocess(person_image) + self.model.batch(0, x1) + self.model.flush() + resultBatchSet = self.model.get_result() + + # Process results + class_batch = resultBatchSet.get(0) + prob_batch = resultBatchSet.get(1) + rect_batch = resultBatchSet.get(2) + + class_batch.get(0, self.class_array) + prob_batch.get(0, self.prob_array) + rect_batch.get(0, self.rect_array) + + class_data = self.class_array[0] + prob_data = self.prob_array[0] + rect_data = self.rect_array[0] + + # Get indices of people classes + person_indices = self.get_number_persons(class_data,prob_data) + + try: + self.number_people = len(person_indices) + except: + self.number_people = 0 + + # Draw bounding boxes on output image + if self.number_people > 0: + for index in person_indices: + + left = np.clip(rect_data[index][0] / np.float(HEIGHT), 0, 1) + top = np.clip(rect_data[index][1] / np.float(WIDTH), 0, 1) + right = np.clip(rect_data[index][2] / np.float(HEIGHT), 0, 1) + bottom = np.clip(rect_data[index][3] / np.float(WIDTH), 0, 1) + + stream.add_rect(left, top, right, bottom) + stream.add_label(str(prob_data[index][0]), right, bottom) + + stream.add_label('People detected: {}'.format(self.number_people), 0.8, 0.05) + + self.model.release_result(resultBatchSet) + outputs.video_out[i] = stream + + return True + + +def main(): + people_counter().run() + +main() +``` + +For sample applications that you can run locally or on the AWS Panorama Appliance, visit the [aws\-panorama\-samples](https://github.com/aws-samples/aws-panorama-samples) repository on GitHub\. \ No newline at end of file diff --git a/docs-source/gettingstarted-concepts.md b/docs-source/gettingstarted-concepts.md new file mode 100644 index 0000000..1e256b6 --- /dev/null +++ b/docs-source/gettingstarted-concepts.md @@ -0,0 +1,28 @@ +# Concepts + +In AWS Panorama, you create computer vision applications and deploy them to the AWS Panorama Appliance to analyze video streams from network cameras\. You write application code in Python and import machine learning models from Amazon SageMaker or Amazon Simple Storage Service \(Amazon S3\)\. Applications use the AWS Panorama Application SDK to receive video input from a datasource and output it to a data sink\. + +**Topics** ++ [The AWS Panorama Appliance](#gettingstarted-concepts-appliance) ++ [Applications](#gettingstarted-concepts-application) ++ [Models](#gettingstarted-concepts-model) + +## The AWS Panorama Appliance + +The AWS Panorama Appliance is the hardware that runs your applications\. You use the AWS Panorama console to register an appliance, update its software, and deploy applications to it\. The software on the AWS Panorama Appliance discovers and connects to camera streams, sends frames of video to your application, and displays video output on an attached display\. + +The AWS Panorama Appliance is an *edge device*\. Instead of sending images to the AWS Cloud for processing, it runs applications locally on optimized hardware\. This enables you to analyze video in real time and process the results with limited connectivity\. The appliance requires an internet connection to report its status, to upload logs, and to get software updates and deployments\. + +For more information, see [Managing the AWS Panorama Appliance](panorama-appliance.md)\. + +## Applications + +Applications run on the AWS Panorama Appliance to do computer vision tasks on video streams\. You can build computer vision applications by combining Python code and machine learning models, and deploy them to the AWS Panorama Appliance over the internet\. Applications can output video to an attached display, or use the AWS SDK to send results to AWS services\. + +For more information, see [Building AWS Panorama applications](panorama-applications.md)\. + +## Models + +A computer vision model is a software program that is trained to detect objects in images\. A model learns to recognize a set of objects by analyzing images of those objects\. It takes an image as input and outputs information about objects that it detects\. + +AWS Panorama supports models built with PyTorch, Apache MXNet, and TensorFlow\. You can build models with Amazon SageMaker and import them from a SageMaker job or an Amazon Simple Storage Service \(Amazon S3\) bucket\. For more information, see [Computer vision models](applications-models.md)\. \ No newline at end of file diff --git a/docs-source/gettingstarted-deploy.md b/docs-source/gettingstarted-deploy.md new file mode 100644 index 0000000..7b77e0d --- /dev/null +++ b/docs-source/gettingstarted-deploy.md @@ -0,0 +1,155 @@ +# Deploying an AWS Panorama application + +After you've [set up your AWS Panorama Appliance Developer Kit](gettingstarted-setup.md) and upgraded its software, deploy a sample application\. In the following sections, you define the application code, import a machine learning model, and deploy an application with the AWS Panorama console\. + +The sample application uses a machine learning model to detect people in frames of video from network camera\. It uses the AWS Panorama Application SDK to load a model, get images, and run the model\. The application then overlays the results on top of the original video and outputs it to a connected display\. + +In a retail setting, analyzing foot traffic patterns enables you to predict traffic levels\. By combining the analysis with other data, you can plan for increased staffing needs around holidays and other events, measure the effectiveness of advertisements and sales promotions, or optimize display placement and inventory management\. + +**Topics** ++ [Create a bucket for storage](#gettingstarted-deploy-createbucket) ++ [Create a Lambda function](#gettingstarted-deploy-code) ++ [Create the application](#gettingstarted-deploy-create) ++ [Deploy the application](#gettingstarted-deploy-deploy) ++ [Clean up](#gettingstarted-deploy-cleanup) ++ [Next steps](#gettingstarted-deploy-next) + +## Create a bucket for storage + +Create an Amazon S3 bucket for the sample model file and Lambda function deployment package\. + +**To create a bucket** + +1. Open the [Amazon S3 console](https://console.aws.amazon.com/s3/home)\. + +1. Choose **Create bucket**\. + +1. Follow the instructions to create a bucket with the following settings: + + **Bucket name** – The name must contain the phrase `aws-panorama`\. For example, `aws-panorama-artifacts-123456789012`\. + + **Region** – The AWS Region where you use AWS Panorama\. + +1. Upload [the model archive](gettingstarted-setup.md#gettingstarted-prerequisites) to the bucket\. + +When the upload operation is complete, view the details of the model file and note the **S3 URL** value for later use\. + +## Create a Lambda function + +Use the Lambda console to create the Lambda function that the application uses to run inference against the model\. The code is stored and versioned in Lambda, but it is not invoked in Lambda\. You deploy the code to the AWS Panorama Appliance Developer Kit and it runs continually while the developer kit is on\. + +When you create a Lambda function, you give it a role that enables it to upload logs and access services with the AWS SDK\. This role is typically used when the function runs in Lambda, but when you run the application on the developer kit, the developer kit's permissions are used\. You can let the Lambda console create a role or, if you don't have permission to create roles, use a role that an administrator creates for you\. + +**To create a Lambda function** + +1. Sign in to the AWS Management Console and open the AWS Lambda console at [https://console\.aws\.amazon\.com/lambda/](https://console.aws.amazon.com/lambda/)\. + +1. Choose **Create function**\. + +1. For **Basic information**, configure the following settings: + + **Function name** – `aws-panorama-sample-function`\. + + **Runtime** – **Python 3\.7**\. + + **Permissions** – To create a new role, use the default setting\. If you have a role that you want to use, choose **Use an existing role**\. + +1. Choose **Create function**\. + +Lambda creates the function and opens the function details page\. Modify the function code and configure the function's runtime settings\. Then, to create an immutable snapshot of the function's code and configuration, publish a version\. + +**To update the function's code and configuration** + +1. For **Function code**, choose **Actions** and then choose **Upload a ZIP file**\. + +1. Upload the [sample code deployment package](samples/aws-panorama-sample.zip) and then choose **Save**\. + +1. When the operation is complete, in the **Runtime settings** section, choose **Edit**\. + +1. Configure the following settings: + + **Handler** – `lambda_function.main`\. In the sample application, the `lambda_function.py` file exports a method named `main` that serves as the handler\. + +1. Choose **Save**\. + +1. In the **Basic settings** section, choose **Edit**\. + +1. Configure the following settings: + + **Timeout** – **2 minutes**\. + + **Memory** – **2048 MB**\. + +1. Choose **Save**\. + +1. Choose **Actions**\. + +1. Choose **Publish new version**\. + +When you configure an application, you choose a function version\. Using a version ensures that the application continues to work if you make changes to the function's code\. To update the application's code, you publish a new version in Lambda and configure the application to use it\. + +## Create the application + +In this example, the application uses a Lambda function named `aws-panorama-sample-function` to run inference against the aws\-panorama\-sample\-model model on video streams from a camera\. The function displays the result on an HDMI display connected to the developer kit\. + +To import the sample model and create an application, use the AWS Panorama console\. + +**To create an application** + +1. Open the AWS Panorama console [Getting started page](https://console.aws.amazon.com/panorama/home#getting-started)\. + +1. Choose **Create application**\. + +1. Complete the workflow with the following settings: + + **Name** – **aws\-panorama\-sample** + + Model source – **External model** + + **Model artifact path** – The Amazon S3 path of the [model archive](gettingstarted-setup.md#gettingstarted-prerequisites)\. For example: **`s3://aws-panorama-artifacts-123456789012/ssd_512_resnet50_v1_voc.tar.gz`** + + **Model name** – **aws\-panorama\-sample\-model** + + This value is used by the application code\. Enter it exactly as shown\. + + **Model framework** – **MXNet** + + **Input name** – **data** + + **Shape** – **1,3,512,512** + + **Lambda functions** – aws\-panorama\-sample\-function version 1 + +The value for **Shape**, `1,3,512,512`, indicates the number of images that the model takes as input \(1\), the number of channels in each image \(3\-\-red, green, and blue\), and the dimensions of the image \(512 x 512\)\. The values and order of the array varies among models\. + +## Deploy the application + +Use the AWS Panorama console to deploy the application to your AWS Panorama Appliance Developer Kit\. AWS Panorama uses AWS IoT Greengrass to deploy the application code and model to the developer kit\. + +**To deploy the application** + +1. Open the AWS Panorama console [Applications page](https://console.aws.amazon.com/panorama/home#applications)\. + +1. To open the application page, choose **aws\-panorama\-sample**\. + +1. Choose **Deploy**\. + +1. Follow the instructions to deploy the application\. + +When the deployment is complete, the application starts processing the video stream and displays the output on the connected monitor\. + +If the application doesn't start running, check the [application and device logs](monitoring-logging.md) in Amazon CloudWatch Logs\. + +## Clean up + +If you are done working with the sample application, you can use the AWS Panorama console to remove it from the developer kit and delete it\. + +**To remove the application from the developer kit** + +1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\. + +1. Choose the developer kit\. + +1. Check the box next to the application's name\. + +1. Choose **Delete application**\. + +**To delete the application from AWS Panorama** + +1. Open the AWS Panorama console [Applications page](https://console.aws.amazon.com/panorama/home#applications)\. + +1. Choose an application\. + +1. Choose **Delete**\. + +The Lambda function and Amazon S3 bucket that you created are not deleted automatically\. You can delete them in the [Lambda console](https://console.aws.amazon.com/lambda/home) and [Amazon S3 console](https://console.aws.amazon.com/s3/home), respectively\. + +## Next steps + +For sample applications that you can run locally or on the AWS Panorama Appliance, visit the [aws\-panorama\-samples](https://github.com/aws-samples/aws-panorama-samples) repository on GitHub\. + +To learn about the AWS Panorama Appliance Developer Kit, continue to [the next topic](gettingstarted-devkit.md)\. \ No newline at end of file diff --git a/docs-source/gettingstarted-devkit.md b/docs-source/gettingstarted-devkit.md new file mode 100644 index 0000000..f1edac8 --- /dev/null +++ b/docs-source/gettingstarted-devkit.md @@ -0,0 +1,193 @@ +# Using the AWS Panorama Appliance Developer Kit + +The AWS Panorama Appliance Developer Kit is an appliance for developing and testing AWS Panorama applications\. You connect to the developer kit from your computer to run commands, view logs, and explore the AWS Panorama Application SDK\. + +**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)\. + +This tutorial provides an introduction to connecting to the device with SSH, viewing logs, and using Python libraries in application code\. + +**Topics** ++ [Prerequisites](#gettingstarted-devkit-prereqs) ++ [Connect with SSH](#gettingstarted-devkit-ssh) ++ [Get superuser access](#gettingstarted-devkit-sudo) ++ [View logs](#gettingstarted-devkit-logs) ++ [View the AWS Panorama Application SDK help](#gettingstarted-devkit-panoramasdk) ++ [Use the AWS SDK for Python \(Boto\)](#gettingstarted-devkit-awssdk) + +## Prerequisites + +To connect to the appliance and run commands, you must enable SSH during [setup](gettingstarted-setup.md)\. + +**Important** +Be sure to record the username and password for SSH\. They are not stored in AWS Panorama\. If you lose them, you must repeat the setup process\. + +To follow the procedures in this tutorial, you need a command line terminal or shell to run commands\. In the code listings, commands are preceded by a prompt symbol \($\) and the name of the current directory, when appropriate\. + +``` +~/lambda-project$ this is a command +this is output +``` + +For long commands, we use an escape character \(`\`\) to split a command over multiple lines\. + +On Linux and macOS, use your preferred shell and package manager\. On Windows 10, you can [install the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to get a Windows\-integrated version of Ubuntu and Bash\. + +This tutorial includes sample scripts that you can run on the appliance as\-is or by replacing some values with your own\. For scripts and other resources that you want to save, you can create a directory under `/data` on the appliance's local storage\. Files outside of `/data` are not saved when you update your appliance's software\. + +## Connect with SSH + +The AWS Panorama Appliance reports its IP address to AWS Panorama\. You can find it in the AWS Panorama console, on the appliance's settings page\. Use this address to connect to the appliance with SSH\. + +**To get an appliance's IP address** + +1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\. + +1. Choose an appliance\. + +1. Choose **Settings**\. + +1. Find the IP address under **Appliance network**\. + +**Note** +The appliance renews its IP address lease with your network's DHCP server automatically\. If you disconnect the appliance from your network for longer than the lease time\. it might be assigned a different IP address\. To avoid this, you can configure a static IP address during [the setup process](gettingstarted-setup.md)\. + +To connect to the appliance, use the `ssh` command with your username and the appliance's IP address\. + +``` +$ ssh 10.24.34.0 -l me +me@10.24.34.0's password: +``` + +To end the session and return to your computer's shell, use the `exit` command\. + +To copy logs and other files from the appliance onto your computer, you can use the `scp` command\. The following example copies the AWS IoT job agent log from an appliance to the current directory\. + +``` +$ scp me@10.0.0.100:/opt/aws/panorama/iot/jobs_agent.log . +me@10.0.0.100's password: +jobs_agent.log 100% 9049KB 372.4KB/s 00:24 +``` + +## Get superuser access + +To use some commands, you need to elevate your privileges\. To assume superuser privileges for a single command, use `sudo`\. For example, to view a protected log file, you can use the `sudo` command with `tail`\. + +``` +me@tegra-ubuntu$ sudo tail /var/log/awslogs.log +``` + +The first time you use `sudo`, you must enter your user password\. You can continue to run commands with `sudo` for a few minutes without entering your password again\. To avoid entering your password multiple times in a session, assume the privileges of the `root` user\. + +``` +me@tegra-ubuntu$ sudo -su root +root@tegra-ubuntu:/home/me# tail /var/log/awslogs.log +``` + +**Important** +Be careful when using root privileges\. Making changes to the software or file system can have unintended consequences\. When you update the appliance, change settings in the AWS Panorama console, or deploy applications, changes to the appliance can be reverted\. + +To exit superuser mode, use the `exit` command\. + +## View logs + +AWS Panorama generates logs in several locations on the appliance\. In addition to logs for your application code,AWS Panorama generates logs for camera streams, outputs, and AWS client processes\. The AWS Panorama Appliance sends many of these logs to Amazon CloudWatch Logs\. + +Your application code's output log is stored under `/data/greengrass`, in a folder structure that includes your AWS Region, account number, and AWS Lambda function name\. To use the following example, replace the account ID and the name of the Lambda function with your own\. + +**Example get\-app\-log\.sh \(requires sudo\) – Show application log** + +``` +REGION=us-east-1 +ACCOUNT=123456789012 +FUNCTION=aws-panorama-sample-function +LOG=/data/greengrass/ggc/var/log/user/$REGION/$ACCOUNT/$FUNCTION.log +tail -100 $LOG +``` + +In addition to application logs, you can view the system logs for AWS IoT Greengrass\. + +**Example list\-greengrass\-logs\.sh \(requires sudo\) – Show application log** + +``` +PANORAMA=/opt/aws/panorama +IOT=$PANORAMA/iot +GREENGRASS=/data/greengrass/ggc/var/log/system +ls $IOT +ls $GREENGRASS +``` + +To view logs for cameras \(datasources\) and HDMI output \(datasinks\), navigate to the `mediapipeline` directory under `/opt/aws/panorama`\. Each camera and display has a separate log file\. + +**Example list\-mediapipeline\-logs\.sh – Get a list of camera and display logs** + +``` +PANORAMA=/opt/aws/panorama +PIPELINE=$PANORAMA/mediapipeline/bin +SOURCES=$PIPELINE/source_onvif-arn-aws-panorama- +SINKS=$PIPELINE/sink_hdmi-datasink-hdmi- +ls $SOURCES* +ls $SINKS* +``` + +The Amazon CloudWatch Logs agent outputs logs to `/var/log/awslogs.log`\. If you don't see logs for your appliance in CloudWatch Logs, check this file for errors\. + +**Example get\-cwl\-log\.sh \(requires sudo\) – Show CloudWatch Logs agent log** + +``` +CWL=/var/log/awslogs.log +tail $CWL +``` + +For more information about using CloudWatch Logs to view logs, see [Viewing AWS Panorama event logs in CloudWatch Logs](monitoring-logging.md)\. + +## View the AWS Panorama Application SDK help + +The AWS Panorama Application SDK is a Python library that is included in the appliance's software image\. You use it in your application code to interact with the appliance and model\. + +To see information about the library, load it into a Python interpreter and use the `help` command\. + +``` +$ python3 +Python 3.7.5 + +>>> import panoramasdk +>>> help(panoramasdk) + + CLASSES + builtins.list(builtins.object) + port + builtins.object + base + batch + batch_set + ... +``` + +The documentation for each class shows details about its methods' behavior and parameters\. + +For more information about the SDK, see [The AWS Panorama Application SDK](applications-panoramasdk.md)\. + +## Use the AWS SDK for Python \(Boto\) + +to access resources in other AWS services, you can use the SDK for Python in your application code When your application code runs, it gets permission to call AWS services from an AWS Identity and Access Management \(IAM\) role that is attached to the device\. + +To call AWS services with the SDK for Python, import the library \(`boto3`\) and create a client\. The following example shows how to use an Amazon Simple Storage Service \(Amazon S3\) client to get a list of objects in an AWS Panorama artifacts bucket\. + +``` +$ python3 +Python 3.7.5 + +>>> import boto3 +>>> s3 = boto3.client('s3') +>>> bucket = 'aws-panorama-artifacts-123456789012' +>>> response = s3.list_objects(Bucket=bucket) +>>> for object in response['Contents']: +... print(f' {object["Key"]}') +... +ssd_512_resnet50_v1_voc.tar.gz +``` + +The AWS Panorama Appliance has limited permissions to access objects in buckets that include `aws-panorama` in the name, and a few other resources\. You can add permissions to the appliance's service role \([AWSPanoramaGreengrassGroupRole](permissions-services.md)\)\. + +Next, learn more about [AWS Panorama concepts](gettingstarted-concepts.md)\. \ No newline at end of file diff --git a/docs-source/gettingstarted-hardware.md b/docs-source/gettingstarted-hardware.md new file mode 100644 index 0000000..5dbdb5c --- /dev/null +++ b/docs-source/gettingstarted-hardware.md @@ -0,0 +1,35 @@ +# AWS Panorama Appliance Developer Kit specifications + +The AWS Panorama Appliance Developer Kit is a pre\-production device for developing and testing AWS Panorama applications\. It has the following hardware specifications\. + +**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)\. + + +| Component | Specification | +| --- | --- | +| Processor | Nvidia Jetson Xavier AGX system\-on\-module \(SOM\) with 32GB RAM | +| Ethernet | RJ\-45 \(x2\) | +| USB | USB 2\.0 \(x1\) and USB 3\.0 \(x1\) type\-A female | +| HDMI | 2\.0a | +| Network adapters | Wi\-Fi: 2x2 MIMO 802\.11ac Ethernet: 2x 1000 Base\-T \(Gigabyte\) | +| Dimensions | 197mm x 243mm x 40mm 7\.75” x 9\.6” x 1\.6” | +| Weight | 3\.7lbs \(1\.7kg\) | +| Mounting options | Rackmount or free standing | +| Power control | Push\-button | +| Reset | Momentary switch | +| Status LED | Programmable 3\-color RGB LED | +| Network LED | Programmable 3\-color RGB LED | +| Power supply | 100V\-240V 50\-60Hz AC 65W | +| Power input | IEC 60320 C6 \(3\-pin\) receptacle | +| Power cord | 6\-foot \(1\.8 meter\) | +| Dust and liquid protection | IP\-62 | +| Operating temperature | \-20°C to 60°C | +| Operating humidity | 0% to 95% RH | +| Storage temperature | \-20°C to 85°C | +| Storage humidity | Uncontrolled for low temperature\. 90%RH at high temperature | +| Certification and regulatory compliance \(EMI and EMC\) | FCC Part\-15 \(US\) | +| Cooling | Forced air \(fan\) heat extraction | +| Thermal touch limits | Meets IEC\-62368 | + +Bluetooth and SD card storage are present on the appliance but are not usable\. \ No newline at end of file diff --git a/docs-source/gettingstarted-models.md b/docs-source/gettingstarted-models.md new file mode 100644 index 0000000..c607749 --- /dev/null +++ b/docs-source/gettingstarted-models.md @@ -0,0 +1,14 @@ +# Supported computer vision models + +AWS Panorama integrates with Amazon SageMaker to support importing and compiling computer vision models for AWS Panorama applications\. You can start with a provided model, or build your own model with a supported framework\. You can import a model from an Amazon Simple Storage Service \(Amazon S3\) bucket or from the output of a SageMaker job\. + +When you deploy an application, AWS Panorama uses the SageMaker Neo compiler to compile it\. SageMaker Neo is a compiler that optimizes models to run efficiently on edge devices such as the AWS Panorama Appliance\. AWS Panorama supports the versions of PyTorch, Apache MXNet, and TensorFlow that are supported for edge devices by SageMaker Neo\. + +**Note** +For a list of models that have been tested with AWS Panorama, see [Model compatibility](https://github.com/awsdocs/aws-panorama-developer-guide/blob/main/resources/model-compatibility.md)\. + +For more information, see the following topics: + +**** ++ [Compile and deploy models with Amazon SageMaker Neo](https://docs.aws.amazon.com/sagemaker/latest/dg/neo.html) ++ [SageMaker Neo supported frameworks and operators](https://aws.amazon.com/releasenotes/sagemaker-neo-supported-frameworks-and-operators/) \ No newline at end of file diff --git a/docs-source/gettingstarted-setup.md b/docs-source/gettingstarted-setup.md new file mode 100644 index 0000000..2685f1f --- /dev/null +++ b/docs-source/gettingstarted-setup.md @@ -0,0 +1,100 @@ +# Setting up the AWS Panorama Appliance Developer Kit + +To get started using your AWS Panorama Appliance Developer Kit, register it in the AWS Panorama console and update its software\. + +**Topics** ++ [Prerequisites](#gettingstarted-prerequisites) ++ [Register and configure the developer kit](#gettingstarted-device) ++ [Upgrade the developer kit software](#gettingstarted-upgrade) ++ [Add a camera stream](#gettingstarted-setup-camera) + +## Prerequisites + +To follow this tutorial, you need an AWS Panorama Appliance Developer Kit and the following hardware: + +**** ++ **Display** – A display with HDMI input for viewing the sample application output ++ **USB drive** \(included\) – A FAT32\-formatted USB flash memory drive with at least 1 GB of storage, for transferring an archive with configuration files and a certificate to the AWS Panorama Appliance Developer Kit ++ **Camera** – A [network\-connected camera](appliance-cameras.md#appliance-cameras-models) that outputs an RTSP video stream for providing input to the camera\. The developer kit can automatically discover streams from cameras that support [ONVIF Profile S](https://www.onvif.org/conformant-products/)\. + +The tutorial uses a sample computer vision model and application code\. Download the model and code before you get started\. + +**** ++ **Model** – [ssd\_512\_resnet50\_v1\_voc\.tar\.gz](samples/ssd_512_resnet50_v1_voc.tar.gz) ++ **Code** – [aws\-panorama\-sample\.zip](samples/aws-panorama-sample.zip) + +The AWS Panorama console uses other AWS services to assemble application components, manage permissions, and verify settings\. To register a developer kit and deploy the sample application, you need access to the following services: + +**** ++ **Amazon Simple Storage Service \(Amazon S3\)** – To store model and Lambda function artifacts, and can be used for application output\. ++ **AWS Lambda** – To manage function code, configuration, and versions\. ++ **AWS Identity and Access Management \(IAM\)** – On first run, to create roles used by the AWS Panorama service, the AWS Panorama console, the AWS Panorama Appliance Developer Kit, AWS IoT Greengrass, SageMaker, and Lambda functions\. + +If you don't have permission to create roles in IAM, have an administrator open [the AWS Panorama console](url-console-domain;panorama/home) and accept the prompt to create service roles\. For the Lambda function's permissions, you can [create an execution role with basic permissions](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) ahead of time, in which case you only need [permission to pass the role](https://docs.aws.amazon.com/lambda/latest/dg/access-control-identity-based.html)\. + +## Register and configure the developer kit + +The AWS Panorama Appliance is a hardware device that connects to network\-enabled cameras over a local network connection\. It uses a Linux\-based operating system that includes the AWS Panorama Application SDK and supporting software for running computer vision applications\. + +To connect to AWS for appliance management and application deployment, the AWS Panorama Appliance Developer Kit uses device certificates\. You use the AWS Panorama console to generate certificates that authenticate the developer kit and authorize it to call AWS API operations\. + +When you set up the AWS Panorama Appliance Developer Kit, enable SSH to so that you can connect to it for testing and debugging\. Do not add cameras at this time\. + +**To register an AWS Panorama Appliance Developer Kit** + +1. Open the AWS Panorama console [Getting started page](https://console.aws.amazon.com/panorama/home#getting-started)\. + +1. Choose **Set up appliance**\. + +1. Follow the instructions to create the appliance resource, configure network access, and download an archive with the device certificate and configuration files\. + +1. Copy the configuration archive to the root directory of the USB drive\. + +1. Connect the USB drive to the developer kit and turn it on\. + +1. The developer kit copies the configuration archive and network configuration file to itself, connects to the network, and connects to the AWS Cloud\. To continue, choose **Next**\. + +1. Follow the instructions to complete setup\. + +## Upgrade the developer kit software + +The AWS Panorama Appliance Developer Kit has several software components, including a Linux operating system, the [AWS Panorama application SDK](applications-panoramasdk.md), and supporting computer vision libraries and frameworks\. To ensure that you can use the latest features and applications with your developer kit, upgrade its software after setup and whenever an update is available\. + +**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**\. + +**Important** +Before you continue, remove the USB drive from the developer kit and format it to delete its contents\. The configuration archive contains sensitive data and is not deleted automatically\. + +The upgrade process can take 30 minutes or more\. + +## Add a camera stream + +After the software upgrade completes, add a camera 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**\. + +Next, [create and deploy the sample application](gettingstarted-deploy.md)\. \ No newline at end of file diff --git a/docs-source/index.md b/docs-source/index.md new file mode 100644 index 0000000..e53a4f7 --- /dev/null +++ b/docs-source/index.md @@ -0,0 +1,56 @@ +# AWS Panorama Developer Guide + +----- +*****Copyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** + +----- +Amazon's trademarks and trade dress may not be used in + connection with any product or service that is not Amazon's, + in any manner that is likely to cause confusion among customers, + or in any manner that disparages or discredits Amazon. All other + trademarks not owned by Amazon are the property of their respective + owners, who may or may not be affiliated with, connected to, or + sponsored by Amazon. + +----- +## Contents ++ [What is AWS Panorama?](panorama-welcome.md) ++ [Getting started with AWS Panorama](panorama-gettingstarted.md) + + [Concepts](gettingstarted-concepts.md) + + [Setting up the AWS Panorama Appliance Developer Kit](gettingstarted-setup.md) + + [Deploying an AWS Panorama application](gettingstarted-deploy.md) + + [Sample application code](gettingstarted-code.md) + + [Using the AWS Panorama Appliance Developer Kit](gettingstarted-devkit.md) + + [Supported computer vision models](gettingstarted-models.md) + + [AWS Panorama Appliance Developer Kit specifications](gettingstarted-hardware.md) ++ [AWS Panorama permissions](panorama-permissions.md) + + [Identity-based IAM policies for AWS Panorama](permissions-roles.md) + + [AWS Panorama service roles and cross-service resources](permissions-services.md) ++ [Managing the AWS Panorama Appliance](panorama-appliance.md) + + [Managing an AWS Panorama Appliance](appliance-manage.md) + + [Managing camera streams for an AWS Panorama Appliance](appliance-cameras.md) + + [Manage applications on an AWS Panorama Appliance](appliance-applications.md) + + [The AWS Panorama Appliance Developer Kit](appliance-devkit.md) + + [AWS Panorama Appliance buttons and lights](appliance-buttons.md) ++ [Building AWS Panorama applications](panorama-applications.md) + + [Managing applications and application versions in AWS Panorama](applications-manage.md) + + [Computer vision models](applications-models.md) + + [Authoring application code](applications-code.md) + + [AWS SDK for Python (Boto3)](applications-awssdk.md) + + [Adding text and boxes to output video](applications-overlays.md) + + [The AWS Panorama Application SDK](applications-panoramasdk.md) ++ [Monitoring AWS Panorama resources and applications](panorama-monitoring.md) + + [Monitoring in the AWS Panorama console](monitoring-console.md) + + [Viewing AWS Panorama event logs in CloudWatch Logs](monitoring-logging.md) ++ [Troubleshooting](panorama-troubleshooting.md) ++ [Security in AWS Panorama](panorama-security.md) + + [Data protection in AWS Panorama](security-dataprotection.md) + + [Identity and access management for AWS Panorama](security-iam.md) + + [How AWS Panorama works with IAM](security_iam_service-with-iam.md) + + [AWS Panorama identity-based policy examples](security_iam_id-based-policy-examples.md) + + [Troubleshooting AWS Panorama identity and access](security_iam_troubleshoot.md) + + [Compliance validation for AWS Panorama](security-compliance.md) + + [Resilience in AWS Panorama](security-resilience.md) + + [Infrastructure security in AWS Panorama](security-infrastructure.md) + + [Network security for AWS Panorama](security-network.md) ++ [Releases](panorama-releases.md) \ No newline at end of file diff --git a/docs-source/monitoring-console.md b/docs-source/monitoring-console.md new file mode 100644 index 0000000..6aaf597 --- /dev/null +++ b/docs-source/monitoring-console.md @@ -0,0 +1,17 @@ +# Monitoring in the AWS Panorama console + +You can use the AWS Panorama console to monitor the your AWS Panorama Appliance and cameras\. The console uses AWS IoT to monitor the state of the appliance + +**To monitor your appliance in the AWS Panorama console** + +1. Open the [AWS Panorama console](https://console.aws.amazon.com/panorama/home)\. + +1. Open the AWS Panorama console [Appliances page](https://console.aws.amazon.com/panorama/home#appliances)\. + +1. Choose an appliance\. + +1. To see the status of the appliance's network interfaces, choose **Settings**\. + +1. To see the status of connected cameras, choose **Camera streams\.**\. + +The overall status of the appliance appears at the top of the page\. If the status is **Online**, then the appliance is connected to AWS and sending regular status updates\. \ No newline at end of file diff --git a/docs-source/monitoring-logging.md b/docs-source/monitoring-logging.md new file mode 100644 index 0000000..afadfff --- /dev/null +++ b/docs-source/monitoring-logging.md @@ -0,0 +1,24 @@ +# Viewing AWS Panorama event logs in CloudWatch Logs + +AWS Panorama reports application events and system events to CloudWatch Logs\. You can use the event logs to help debugging your AWS Panorama application or troubleshoot application configuration when you encounter any issues\. + +To debug and validate that your code is working as expected, you can output logs with the standard logging functionality for Python\. You can view logs in the CloudWatch Logs console\. + +**To view logs in CloudWatch Logs** + +1. Open the [Log groups page of the CloudWatch Logs console](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) + +1. Find AWS Panorama application and appliance logs in the following groups: + +**** + + **Application code** – `/aws/greengrass/Lambda/us-east-1/123456789012/function-name` + + Replace the highlighted values with your AWS Region, account ID, and function name\. + + **AWS IoT Greengrass system** – `/aws/greengrass/GreengrassSystem/component-name` + + **AWS Panorama Appliance system** – `/aws/panorama_appliance/iot-thing-name` + + Log streams include `syslog`, `iot_job_agent`, `mediapipeline`, and a stream for each camera\. + +If you don't see logs in CloudWatch Logs, confirm that you are in the correct AWS Region\. If you are, there might be an issue with the appliance's connection to AWS, or with permissions on [the appliance's AWS Identity and Access Management \(IAM\) role](permissions-services.md)\. + +With the AWS Panorama Appliance Developer Kit, you can connect to the appliance over a local network to view logs and configuration files\. For more information, see [Using the AWS Panorama Appliance Developer Kit](gettingstarted-devkit.md)\. \ No newline at end of file diff --git a/docs-source/panorama-appliance.md b/docs-source/panorama-appliance.md new file mode 100644 index 0000000..46cffb4 --- /dev/null +++ b/docs-source/panorama-appliance.md @@ -0,0 +1,16 @@ +# Managing the AWS Panorama Appliance + +The AWS Panorama Appliance is the hardware that runs your applications\. You use the AWS Panorama console to register an appliance, update its software, and deploy applications to it\. The software on the AWS Panorama Appliance discovers and connects to camera streams, sends frames of video to your application, and displays video output on an attached display\. + +During the setup process, you connect cameras to the appliance for use with applications\. You can [manage an appliance's cameras](appliance-cameras.md) in the AWS Panorama console\. When you deploy an application, you choose which camera streams the appliance sends to it for processing\. + +[The AWS Panorama Appliance Developer Kit](appliance-devkit.md) is a version of the AWS Panorama Appliance with developer features enabled\. You can connect to the AWS Panorama Appliance Developer Kit over a local network to run commands, view logs, and explore the AWS Panorama SDK\. + +For tutorials that introduce the AWS Panorama Appliance with a sample application, see [Getting started with AWS Panorama](panorama-gettingstarted.md)\. + +**Topics** ++ [Managing an AWS Panorama Appliance](appliance-manage.md) ++ [Managing camera streams for an AWS Panorama Appliance](appliance-cameras.md) ++ [Manage applications on an AWS Panorama Appliance](appliance-applications.md) ++ [The AWS Panorama Appliance Developer Kit](appliance-devkit.md) ++ [AWS Panorama Appliance buttons and lights](appliance-buttons.md) \ No newline at end of file diff --git a/docs-source/panorama-applications.md b/docs-source/panorama-applications.md new file mode 100644 index 0000000..4dac05c --- /dev/null +++ b/docs-source/panorama-applications.md @@ -0,0 +1,17 @@ +# Building AWS Panorama applications + +Applications run on the AWS Panorama Appliance to do computer vision tasks on video streams\. You can build computer vision applications by combining Python code and machine learning models, and deploy them to the AWS Panorama Appliance over the internet\. Applications can output video to an attached display, or use the AWS SDK to send results to AWS services\. + +A [model](applications-models.md) analyzes images to detect people, vehicles, and other objects\. Based on images that it has previously seen, the model tells you what it thinks something is, and how confident it is in its guess\. You can train models with your own image data or get started with a sample\. + +The application's [code](applications-code.md) loads a model, sends still images to it, and processes the result\. A model might detect multiple objects and return their shape and location\. The code can use this information to draw overlays on the video or send results to an AWS service for storage or further processing\. + +To get images from a stream, interact with a model, and output video, application code uses [the AWS Panorama Application SDK](applications-panoramasdk.md)\. The SDK is a Python library that supports models generated with PyTorch, Apache MXNet, and TensorFlow\. + +**Topics** ++ [Managing applications and application versions in AWS Panorama](applications-manage.md) ++ [Computer vision models](applications-models.md) ++ [Authoring application code](applications-code.md) ++ [AWS SDK for Python \(Boto3\)](applications-awssdk.md) ++ [Adding text and boxes to output video](applications-overlays.md) ++ [The AWS Panorama Application SDK](applications-panoramasdk.md) \ No newline at end of file diff --git a/docs-source/panorama-gettingstarted.md b/docs-source/panorama-gettingstarted.md new file mode 100644 index 0000000..52985c5 --- /dev/null +++ b/docs-source/panorama-gettingstarted.md @@ -0,0 +1,19 @@ +# Getting started with AWS Panorama + +To get started with AWS Panorama, use the AWS Panorama console to register your AWS Panorama Appliance Developer Kit and create an application\. In about an hour, you can configure the device, update its software, and deploy a sample application\. To complete the tutorials in this section, you use the AWS Panorama Appliance Developer Kit and a camera that streams video over a local network\. + +The sample application analyzes a video stream to tally the number of people detected and display the results on a connected display\. It includes a model that has been trained with SageMaker and [sample code](gettingstarted-code.md) that uses the AWS Panorama Application SDK to run inference and output video\. + +**Note** +For sample applications that you can run locally or on the AWS Panorama Appliance, visit the [aws\-panorama\-samples](https://github.com/aws-samples/aws-panorama-samples) repository on GitHub\. + +After you've used the developer kit with the sample application, [connect to the AWS Panorama Appliance Developer Kit](gettingstarted-devkit.md) with SSH\. When you are logged in to the appliance, you can explore the execution environment and view logs for applications, cameras, and the appliance itself\. + +**Topics** ++ [Concepts](gettingstarted-concepts.md) ++ [Setting up the AWS Panorama Appliance Developer Kit](gettingstarted-setup.md) ++ [Deploying an AWS Panorama application](gettingstarted-deploy.md) ++ [Sample application code](gettingstarted-code.md) ++ [Using the AWS Panorama Appliance Developer Kit](gettingstarted-devkit.md) ++ [Supported computer vision models](gettingstarted-models.md) ++ [AWS Panorama Appliance Developer Kit specifications](gettingstarted-hardware.md) \ No newline at end of file diff --git a/docs-source/panorama-monitoring.md b/docs-source/panorama-monitoring.md new file mode 100644 index 0000000..0f933dd --- /dev/null +++ b/docs-source/panorama-monitoring.md @@ -0,0 +1,11 @@ +# Monitoring AWS Panorama resources and applications + +You can monitor AWS Panorama resources in the AWS Panorama console and with CloudWatch Logs\. The AWS Panorama Appliance connects to the AWS Cloud over the internet to report its status and the status of connected cameras\. While it is on, the appliance also sends logs to CloudWatch Logs in real time\. + +The appliance gets permission to use AWS IoT, CloudWatch Logs, and other services from a service role that you create the first time that you use the AWS Panorama console\. For more information, see [AWS Panorama service roles and cross\-service resources](permissions-services.md)\. + +For help troubleshooting specific errors, see [Troubleshooting](panorama-troubleshooting.md)\. + +**Topics** ++ [Monitoring in the AWS Panorama console](monitoring-console.md) ++ [Viewing AWS Panorama event logs in CloudWatch Logs](monitoring-logging.md) \ No newline at end of file diff --git a/docs-source/panorama-permissions.md b/docs-source/panorama-permissions.md new file mode 100644 index 0000000..94dcfd1 --- /dev/null +++ b/docs-source/panorama-permissions.md @@ -0,0 +1,17 @@ +# AWS Panorama permissions + +AWS Panorama uses other AWS services to access required AWS resources on your behalf\. The dependent services include the following: ++ AWS Identity and Access Management for managing access permissions\. ++ AWS IoT and AWS IoT Greengrass for managing the AWS Panorama Appliance in the cloud\. ++ AWS Lambda for running inference against trained models and process application data\. ++ Amazon S3 for storing model artifacts and other application data\. ++ SageMaker for importing trained machine learning models and optimizing models during deployment\. ++ Amazon CloudWatch Logs for logging application events and metrics\. + +To enable AWS Panorama to access AWS services and resources, you create service roles the first time that you use the AWS Panorama console\. + +For more information on the IAM roles and policies, see [AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)\. + +**Topics** ++ [Identity\-based IAM policies for AWS Panorama](permissions-roles.md) ++ [AWS Panorama service roles and cross\-service resources](permissions-services.md) \ No newline at end of file diff --git a/docs-source/panorama-releases.md b/docs-source/panorama-releases.md new file mode 100644 index 0000000..76d4744 --- /dev/null +++ b/docs-source/panorama-releases.md @@ -0,0 +1,7 @@ +# Releases + +The following table shows when features and software updates were released for the AWS Panorama service, software, and documentation\. To ensure that you have access to all features, [update your AWS Panorama Appliance](appliance-manage.md#appliance-manage-software) to the latest software version\. For more information on a release, see the linked topic\. + +| Change | Description | Date | +| --- |--- |--- | +| [Preview](#panorama-releases) | AWS Panorama is now available by invitation in the US East \(N\. Virginia\) and US West \(Oregon\) Regions\. To apply to purchase an AWS Panorama Appliance Developer Kit, visit [AWS Panorama](https://aws.amazon.com/panorama)\. | December 1, 2020 | \ No newline at end of file diff --git a/docs-source/panorama-security.md b/docs-source/panorama-security.md new file mode 100644 index 0000000..72e377a --- /dev/null +++ b/docs-source/panorama-security.md @@ -0,0 +1,17 @@ +# Security in AWS Panorama + +Cloud security at AWS is the highest priority\. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security\-sensitive organizations\. + +Security is a shared responsibility between AWS and you\. The [shared responsibility model](http://aws.amazon.com/compliance/shared-responsibility-model/) describes this as security *of* the cloud and security *in* the cloud: ++ **Security of the cloud** – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud\. AWS also provides you with services that you can use securely\. Third\-party auditors regularly test and verify the effectiveness of our security as part of the [AWS compliance programs](http://aws.amazon.com/compliance/programs/)\. To learn about the compliance programs that apply to AWS Panorama, see [AWS Services in Scope by Compliance Program](http://aws.amazon.com/compliance/services-in-scope/)\. ++ **Security in the cloud** – Your responsibility is determined by the AWS service that you use\. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations\. + +This documentation helps you understand how to apply the shared responsibility model when using AWS Panorama\. The following topics show you how to configure AWS Panorama to meet your security and compliance objectives\. You also learn how to use other AWS services that help you to monitor and secure your AWS Panorama resources\. + +**Topics** ++ [Data protection in AWS Panorama](security-dataprotection.md) ++ [Identity and access management for AWS Panorama](security-iam.md) ++ [Compliance validation for AWS Panorama](security-compliance.md) ++ [Resilience in AWS Panorama](security-resilience.md) ++ [Infrastructure security in AWS Panorama](security-infrastructure.md) ++ [Network security for AWS Panorama](security-network.md) \ No newline at end of file diff --git a/docs-source/panorama-troubleshooting.md b/docs-source/panorama-troubleshooting.md new file mode 100644 index 0000000..df42826 --- /dev/null +++ b/docs-source/panorama-troubleshooting.md @@ -0,0 +1,45 @@ +# Troubleshooting + +The following topics provide troubleshooting advice for errors and issues that you might encounter when using the AWS Panorama console, appliance, or SDK\. If you find an issue that is not listed here, you can use the **Provide feedback** button on this page to report it\. + +For more troubleshooting advice and answers to common support questions, visit the [AWS Knowledge Center](https://aws.amazon.com/premiumsupport/knowledge-center/)\. + +## Application configuration + +**Error:** *Unable to parse model configuration \.\.\. parseFile\(1145\) unable to open file* + +The name of the model in AWS Panorama must match the name of the model parameter in your application code\. You refer to this name when you load a model with the `panoramasdk` module\. + +## Appliance configuration + +**Error:** *Resource temporarily unavailable* \(SSH\) + +Check the network connection to the appliance\. A VPN client or firewall software can block connections\. If you reboot the AWS Panorama Appliance Developer Kit without the USB drive that contains the configuration archive, SSH is deactivated\. + +**Issue:** *The appliance shows a blank screen during boot up\.* + +After completing the initial boot sequence, which takes about one minute, the appliance shows a blank screen for a minute or more while it loads your model and starts your application\. Also, the appliance does not output video if you connect a display after it turns on\. + +**Issue:** *The appliance doesn't respond when I hold the power button down to turn it off\.* + +The appliance takes up to 10 seconds to shut down safely\. You need to hold the power button down for only 1 second to start the shutdown sequence\. For a complete list of button operations, see [AWS Panorama Appliance buttons and lights](appliance-buttons.md)\. + +**Issue:** *I need to generate a new configuration archive to change settings or replace a lost certificate\.* + +AWS Panorama does not store the device certificate or network configuration after you download it\. If you still have the archive and need to modify the network configuration, you can extract the `network.json` file, modify it, and update the archive\. If you don't have the archive, you can delete the appliance using the AWS Panorama console and create a new one with a new configuration bundle\. + +## Camera configuration + +**Error:** *No camera has been found in the subnet\. Please verify that there is at least one camera in the subnet* + +Automatic camera discovery uses [ONVIF profile S](https://www.onvif.org/conformant-products/) to search for camera streams on the appliance's local network\. If your camera does not support ONVIF or if automatic discovery doesn't work for some other reason, you can connect to a stream manually by entering the camera's IP address and RTSP stream URL\. For example: `rtsp://10.0.0.99/live/mpeg4`\. The path part of the URL varies depending on your camera\. + +**Error:** *Failed to set up the "video/H264" subsession: 461 Unsupported transport* + +**Error:** *Bit stream out of bounds\.* + +**Error:** *initNal\(63\) Error encountered while processing NAL\.* + +If you can connect the appliance to the camera in the AWS Panorama console, but errors such as these appear in the appliance logs, there may be an issue with the camera or the appliance software\. Use the **Provide feedback** link on this page to send us the camera model and error\. + +For a list of cameras that have been tested for compatibility with the AWS Panorama Appliance, see [Supported camera models](appliance-cameras.md#appliance-cameras-models)\. \ No newline at end of file diff --git a/docs-source/panorama-welcome.md b/docs-source/panorama-welcome.md new file mode 100644 index 0000000..a8632c5 --- /dev/null +++ b/docs-source/panorama-welcome.md @@ -0,0 +1,26 @@ +# What is AWS Panorama? + +With AWS Panorama, you can build computer vision applications for your business or customers without purchasing special cameras\. By using the AWS Panorama Appliance with your existing network cameras, you can run applications that use machine learning \(ML\) to collect data from video streams, output video with text and graphical overlays, and interact with other AWS services\. AWS Panorama applications run computer vision workloads locally on the AWS Panorama Appliance and can communicate with AWS services to store results and run secondary workflows\. + +The AWS Panorama Appliance is a compact edge appliance that uses a powerful system\-on\-module \(SOM\) that is optimized for machine learning workloads\. The appliance can run multiple computer vision models against multiple video streams in parallel and output the results in real time\. It is designed for use in commercial and industrial settings and is rated for dust and liquid protection \(IP\-62\)\. + +**Note** +AWS Panorama is available in preview with the AWS Panorama Appliance Developer Kit for developing computer vision applications in a non\-production environment\. The AWS Panorama Appliance will be available at AWS Panorama GA\. To get an AWS Panorama Appliance Developer Kit, visit [aws\.amazon\.com/panorama](https://aws.amazon.com/panorama)\. + +The AWS Panorama Appliance enables you to run self\-contained computer vision applications at the edge, without sending images to the AWS Cloud\. By using the AWS SDK, you can integrate with other AWS services and use them to track data from the application over time\. By integrating with other AWS services, you can use AWS Panorama to do the following: + +**** ++ **Improve quality control** – Monitor an assembly line's output to identify widgets that don't conform to requirements\. Highlight images of nonconformant widgets with text and a bounding box and display them on a monitor for review by your quality control team\. ++ **Analyze traffic patterns** – Use the AWS SDK to record data for retail analytics in Amazon DynamoDB\. Use a serverless application to analyze the collected data over time, detect anomalies in the data, and predict future behavior\. ++ **Receive notifications** – Monitor workplace safety and social distancing\. When your application detects a potentially unsafe situation, upload the image to Amazon Simple Storage Service \(Amazon S3\) and send a notification to an Amazon Simple Notification Service \(Amazon SNS\) topic so recipients can take corrective action\. ++ **Collect training and test data** – Upload images of objects that your computer vision model couldn't identify, or where the model's confidence in its guess was borderline\. Use a serverless application to create a queue of images that need to be tagged\. Tag the images and use them to retrain the model in Amazon SageMaker\. + +AWS Panorama uses other AWS services to manage the AWS Panorama Appliance, access models and code, and deploy applications\. AWS Panorama does as much as possible without requiring you to interact with other services, but a knowledge of the following services can help you understand how AWS Panorama works\. + +**** ++ [SageMaker](https://aws.amazon.com/sagemaker/) – Collect training data from cameras or sensors, build and train a machine learning model, and optimize it for use on hardware such as the AWS Panorama Appliance\. AWS Panorama can import trained computer vision models from SageMaker, and it uses SageMaker Neo to optimize models to run on the AWS Panorama Appliance\. ++ [Amazon S3](https://aws.amazon.com/s3/) – Store trained models, even those built with an ML framework other than SageMaker, for use with AWS Panorama\. You can also use Amazon S3 to store your application code\. ++ [AWS Lambda](https://aws.amazon.com/lambda/) – You author AWS Panorama application code in Lambda\. Although your code doesn't run in Lambda, you can use it for versioning and to store the application code that AWS Panorama deploys to the AWS Panorama Appliance\. ++ [AWS IoT](https://aws.amazon.com/iot/) – AWS Panorama uses AWS IoT services to monitor the state of the AWS Panorama Appliance, manage software updates, and deploy applications\. You don't need to use AWS IoT directly\. + +To get started with the AWS Panorama Appliance and learn more about the service, continue to [the next chapter](panorama-gettingstarted.md)\. \ No newline at end of file diff --git a/docs-source/permissions-roles.md b/docs-source/permissions-roles.md new file mode 100644 index 0000000..3091801 --- /dev/null +++ b/docs-source/permissions-roles.md @@ -0,0 +1,283 @@ +# Identity\-based IAM policies for AWS Panorama + +To grant users in your account access to AWS Panorama, you use identity\-based policies in AWS Identity and Access Management \(IAM\)\. Identity\-based policies can apply directly to IAM users, or to IAM groups and roles that are associated with a user\. You can also grant users in another account permission to assume a role in your account and access your AWS Panorama resources\. + +AWS Panorama provides managed policies that grant access to AWS Panorama API actions and, in some cases, access to other services used to develop and manage AWS Panorama resources\. AWS Panorama updates the managed policies as needed, to ensure that your users have access to new features when they're released\. ++ **AWSPanoramaFullAccess** – Grants full access to AWS Panorama\. [View policy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSPanoramaFullAccess) + +Managed policies grant permission to API actions without restricting the resources that a user can modify\. For finer\-grained control, you can create your own policies that limit the scope of a user's permissions\. + +At a minimum, an AWS Panorama user needs permission to use the following services in addition to AWS Panorama: + +**** ++ **Amazon Simple Storage Service \(Amazon S3\)** – To store model and Lambda function artifacts, and can be used for application output\. ++ **AWS Lambda** – To manage function code, configuration, and versions\. ++ **IAM** – To create a Lambda function, a user needs access to assign a role to the function\. You can [create an execution role with basic permissions](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) ahead of time, in which case the user needs only [permission to pass the role](https://docs.aws.amazon.com/lambda/latest/dg/access-control-identity-based.html)\. + +**** +The first time you use [the AWS Panorama console](https://console.aws.amazon.com/panorama/home), you need permission to create service roles used by the AWS Panorama service, the AWS Panorama console, the AWS Panorama Appliance, AWS IoT Greengrass, and SageMaker\. A [service role](permissions-services.md) gives a service permission to manage resources or interact with other services\. Create these roles before granting access to your users\. + +To create machine learning models or to monitor application output in the console, additional permissions are required\. To use all features of AWS Panorama, also grant a user permission to use the following services: + +**** ++ **Amazon SageMaker** – Develop, train, and compile machine learning models optimized for the AWS Panorama Appliance ++ **Amazon CloudWatch** – View metrics output by AWS Panorama, Lambda, and other services ++ **Amazon CloudWatch Logs** – View application logs + +You can grant full access to each service or limit the scope of permissions by resource name\. The following example shows a policy that provides limited access to resources in AWS Panorama and related services\. The `Resources` key for applicable actions limits access to resources whose names start with `panorama`\. + +**Example user policy** + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "PanoramaIoTThingAccess", + "Effect": "Allow", + "Action": [ + "iot:CreateThing", + "iot:DeleteThing", + "iot:DeleteThingShadow", + "iot:DescribeThing", + "iot:GetThingShadow", + "iot:UpdateThing", + "iot:UpdateThingShadow" + ], + "Resource": [ + "arn:aws:iot:*:*:thing/panorama*" + ] + }, + { + "Sid": "PanoramaIoTCertificateAccess", + "Effect": "Allow", + "Action": [ + "iot:AttachThingPrincipal", + "iot:DetachThingPrincipal", + "iot:UpdateCertificate", + "iot:DeleteCertificate", + "iot:AttachPrincipalPolicy", + "iot:DetachPrincipalPolicy" + ], + "Resource": [ + "arn:aws:iot:*:*:thing/panorama*", + "arn:aws:iot:*:*:cert/*" + ] + }, + { + "Sid": "PanoramaIoTCreateCertificateAndPolicyAccess", + "Effect": "Allow", + "Action": [ + "iot:CreateKeysAndCertificate", + "iot:CreatePolicy", + "iot:CreatePolicyVersion" + ], + "Resource": [ + "*" + ] + }, + { + "Sid": "PanoramaIoTJobAccess", + "Effect": "Allow", + "Action": [ + "iot:DescribeJobExecution", + "iot:CreateJob", + "iot:DeleteJob" + ], + "Resource": [ + "arn:aws:iot:*:*:job/panorama*", + "arn:aws:iot:*:*:thing/panorama*" + ] + }, + { + "Sid": "PanoramaIoTEndpointAccess", + "Effect": "Allow", + "Action": [ + "iot:DescribeEndpoint" + ], + "Resource": [ + "*" + ] + }, + { + "Sid": "PanoramaAccess", + "Effect": "Allow", + "Action": [ + "panorama:*" + ], + "Resource": [ + "*" + ] + }, + { + "Sid": "PanoramaS3ObjectAccess", + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject" + ], + "Resource": [ + "arn:aws:s3:::panorama*" + ] + }, + { + "Sid": "PanoramaS3Buckets", + "Effect": "Allow", + "Action": [ + "s3:DeleteBucket", + "s3:ListBucket", + "s3:GetBucket*" + ], + "Resource": [ + "arn:aws:s3:::panorama*" + ] + }, + { + "Sid": "PanoramaCreateS3Buckets", + "Effect": "Allow", + "Action": [ + "s3:CreateBucket" + ], + "Resource": [ + "arn:aws:s3:::panorama*" + ] + }, + { + "Sid": "PanoramaIAMPassRoleAccess", + "Effect": "Allow", + "Action": [ + "iam:PassRole" + ], + "Resource": [ + "arn:aws:iam::*:role/AWSPanorama*", + "arn:aws:iam::*:role/service-role/AWSPanorama*" + ], + "Condition": { + "StringEquals": { + "iam:PassedToService": [ + "greengrass.amazonaws.com", + "sagemaker.amazonaws.com" + ] + } + } + }, + { + "Sid": "PanoramaIAMLambdaPassRoleAccess", + "Effect": "Allow", + "Action": [ + "iam:PassRole" + ], + "Resource": [ + "arn:aws:iam::*:role/AWSPanorama*", + "arn:aws:iam::*:role/service-role/AWSPanorama*" + ], + "Condition": { + "StringEqualsIfExists": { + "iam:PassedToService": "lambda.amazonaws.com" + } + } + }, + { + "Sid": "PanoramaGreenGrassAccess", + "Effect": "Allow", + "Action": [ + "greengrass:*" + ], + "Resource": [ + "*" + ] + }, + { + "Sid": "PanoramaLambdaAdminFunctionAccess", + "Effect": "Allow", + "Action": [ + "lambda:CreateFunction", + "lambda:DeleteFunction", + "lambda:GetFunction", + "lambda:GetFunctionConfiguration", + "lambda:ListFunctions", + "lambda:ListVersionsByFunction", + "lambda:PublishVersion", + "lambda:UpdateFunctionCode", + "lambda:UpdateFunctionConfiguration" + ], + "Resource": [ + "arn:aws:lambda:*:*:function:panorama*" + ] + }, + { + "Sid": "PanoramaLambdaUsersFunctionAccess", + "Effect": "Allow", + "Action": [ + "lambda:GetFunction", + "lambda:GetFunctionConfiguration", + "lambda:ListFunctions", + "lambda:ListVersionsByFunction" + ], + "Resource": [ + "arn:aws:lambda:*:*:function:*" + ] + }, + { + "Sid": "PanoramaSageMakerWriteAccess", + "Effect": "Allow", + "Action": [ + "sagemaker:CreateTrainingJob", + "sagemaker:StopTrainingJob", + "sagemaker:CreateCompilationJob", + "sagemaker:DescribeCompilationJob", + "sagemaker:StopCompilationJob" + ], + "Resource": [ + "arn:aws:sagemaker:*:*:training-job/panorama*", + "arn:aws:sagemaker:*:*:compilation-job/panorama*" + ] + }, + { + "Sid": "PanoramaSageMakerListAccess", + "Effect": "Allow", + "Action": [ + "sagemaker:ListCompilationJobs" + ], + "Resource": [ + "*" + ] + }, + { + "Sid": "PanoramaSageMakerReadAccess", + "Effect": "Allow", + "Action": [ + "sagemaker:DescribeTrainingJob" + ], + "Resource": [ + "arn:aws:sagemaker:*:*:training-job/*" + ] + }, + { + "Sid": "PanoramaCWLogsAccess", + "Effect": "Allow", + "Action": [ + "iot:AttachPolicy", + "iot:CreateRoleAlias" + ], + "Resource": [ + "arn:aws:iot:*:*:policy/panorama*", + "arn:aws:iot:*:*:rolealias/panorama*" + ] + } + ] +} +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Service": "panorama.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] +} +``` \ No newline at end of file diff --git a/docs-source/permissions-services.md b/docs-source/permissions-services.md new file mode 100644 index 0000000..c54cc19 --- /dev/null +++ b/docs-source/permissions-services.md @@ -0,0 +1,35 @@ +# AWS Panorama service roles and cross\-service resources + +AWS Panorama uses other AWS services to manage the AWS Panorama Appliance, store data, and import application resources\. These services also call other services using permissions managed with AWS Identity and Access Management \(IAM\) service roles\. A service role gives a service permission to manage resources or interact with other services\. When you sign in to the AWS Panorama console for the first time, you create the following service roles: + +**** ++ **AWSPanoramaServiceRole** – Allows AWS Panorama to manage resources in Amazon Simple Storage Service \(Amazon S3\), AWS IoT, AWS IoT Greengrass, AWS Lambda, Amazon SageMaker, and Amazon CloudWatch, and to pass service roles to AWS IoT, AWS IoT Greengrass, and SageMaker + + Managed policy: [AWSPanoramaServiceRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/aws-service-role/AWSPanoramaServiceRolePolicy) ++ **AWSPanoramaApplianceRole** – Allows AWS IoT software on an AWS Panorama Appliance to upload logs to CloudWatch + + Managed policy: [AWSPanoramaApplianceRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/aws-service-role/AWSPanoramaApplianceRolePolicy) ++ **AWSPanoramaSageMakerRole** – Allows SageMaker to manage objects in buckets created for use with AWS Panorama + + Managed policy: [AWSPanoramaSageMakerRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/aws-service-role/AWSPanoramaSageMakerRolePolicy) ++ **AWSPanoramaGreengrassGroupRole** – Allows a Lambda function on an AWS Panorama Appliance to manage resources in AWS Panorama, upload logs and metrics to CloudWatch, and manage objects in buckets created for use with AWS Panorama + + Managed policy: [AWSPanoramaGreengrassGroupRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/aws-service-role/AWSPanoramaGreengrassGroupRolePolicy) ++ **AWSPanoramaGreengrassRole** – Grants AWS IoT Greengrass permission to access resources in Lambda, SageMaker, Amazon S3, and AWS IoT + + Managed policy: [AWSGreengrassResourceAccessRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/aws-service-role/AWSGreengrassResourceAccessRolePolicy) + +To view the permissions attached to each role, use the [IAM console](https://console.aws.amazon.com/iam)\. Wherever possible, the role's permissions are restricted to resources that match a naming pattern that AWS Panorama uses\. For example, **AWSPanoramaServiceRole** grants only permission for the service to access Amazon S3 buckets that include the phrase `aws-panorama`\. + +AWS Panorama creates or accesses resources in the following services: + +**** ++ [AWS IoT](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsiot.html) – Things, policies, certificates, and jobs for the AWS Panorama Appliance ++ [Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html) – Buckets and objects for model storage and application output ++ [AWS IoT Greengrass](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsiotgreengrass.html) – A [Greengrass resource](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsiotgreengrass.html#awsiotgreengrass-resources-for-iam-policies) that manages the AWS Panorama Appliance ++ [Lambda](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awslambda.html) – Lambda functions that perform inference or process data in an application ++ [SageMaker](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonsagemaker.html) – A [training job](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonsagemaker.html#amazonsagemaker-resources-for-iam-policies) that trains a model for use with an application ++ [CloudWatch Logs](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoncloudwatchlogs.html) – Log groups and log streams for application logs ++ [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html) – Service roles and Lambda function runtime roles + +For information about Amazon Resource Name \(ARN\) format or permission scopes for each service, see the topics in the *IAM User Guide* that are linked to in this list\. \ No newline at end of file diff --git a/docs-source/security-compliance.md b/docs-source/security-compliance.md new file mode 100644 index 0000000..130cc3b --- /dev/null +++ b/docs-source/security-compliance.md @@ -0,0 +1,14 @@ +# Compliance validation for AWS Panorama + +Third\-party auditors assess the security and compliance of AWS Panorama as part of multiple AWS compliance programs\. These include SOC, PCI, FedRAMP, HIPAA, and others\. + +For a list of AWS services in scope of specific compliance programs, see [AWS services in scope by compliance program](http://aws.amazon.com/compliance/services-in-scope/)\. For general information, see [AWS compliance programs](http://aws.amazon.com/compliance/programs/)\. + +You can download third\-party audit reports using AWS Artifact\. For more information, see [Downloading reports in AWS artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)\. + +Your compliance responsibility when using AWS Panorama is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations\. AWS provides the following resources to help with compliance: ++ [Security and compliance quick start guides](http://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance) – These deployment guides discuss architectural considerations and provide steps for deploying security\- and compliance\-focused baseline environments on AWS\. ++ [Architecting for HIPAA security and compliance whitepaper ](https://d0.awsstatic.com/whitepapers/compliance/AWS_HIPAA_Compliance_Whitepaper.pdf) – This whitepaper describes how companies can use AWS to create HIPAA\-compliant applications\. ++ [AWS compliance resources](http://aws.amazon.com/compliance/resources/) – This collection of workbooks and guides might apply to your industry and location\. ++ [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) – This AWS service assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations\. ++ [AWS Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) – This AWS service provides a comprehensive view of your security state within AWS that helps you check your compliance with security industry standards and best practices\. \ No newline at end of file diff --git a/docs-source/security-dataprotection.md b/docs-source/security-dataprotection.md new file mode 100644 index 0000000..e776a3b --- /dev/null +++ b/docs-source/security-dataprotection.md @@ -0,0 +1,33 @@ +# Data protection in AWS Panorama + +The AWS [shared responsibility model](http://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in AWS Panorama\. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud\. You are responsible for maintaining control over your content that is hosted on this infrastructure\. This content includes the security configuration and management tasks for the AWS services that you use\. For more information about data privacy, see the [Data Privacy FAQ](http://aws.amazon.com/compliance/data-privacy-faq)\. For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](http://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*\. + +For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management \(IAM\)\. That way each user is given only the permissions necessary to fulfill their job duties\. We also recommend that you secure your data in the following ways: ++ Use multi\-factor authentication \(MFA\) with each account\. ++ Use SSL/TLS to communicate with AWS resources\. We recommend TLS 1\.2 or later\. ++ Set up API and user activity logging with AWS CloudTrail\. ++ Use AWS encryption solutions, along with all default security controls within AWS services\. ++ Use advanced managed security services such as Amazon Macie, which assists in discovering and securing personal data that is stored in Amazon S3\. ++ If you require FIPS 140\-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint\. For more information about the available FIPS endpoints, see [Federal Information Processing Standard \(FIPS\) 140\-2](http://aws.amazon.com/compliance/fips/)\. + +We strongly recommend that you never put sensitive identifying information, such as your customers' account numbers, into free\-form fields such as a **Name** field\. This includes when you work with AWS Panorama or other AWS services using the console, API, AWS CLI, or AWS SDKs\. Any data that you enter into AWS Panorama or other services might get picked up for inclusion in diagnostic logs\. When you provide a URL to an external server, don't include credentials information in the URL to validate your request to that server\. + +**Topics** ++ [Encryption in transit](#security-privacy-intransit) ++ [Encryption at rest](#security-privacy-atrest) + +## Encryption in transit + +AWS Panorama API endpoints support secure connections only over HTTPS\. When you manage AWS Panorama resources with the AWS Management Console, AWS SDK, or the AWS Panorama API, all communication is encrypted with Transport Layer Security \(TLS\)\. + +For a complete list of API endpoints, see [AWS Regions and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the *AWS General Reference*\. + +## Encryption at rest + +The AWS Panorama service does not copy or store data such as machine learning models and application code\. These artifacts are stored in other services and AWS Panorama uses AWS IoT Greengrass to copy them onto the AWS Panorama Appliance\. + +The contents of the configuration archive, which includes the appliance's private key and network configuration, are not encrypted\. The network configuration file contains the Wi\-Fi password and SSH credentials in plain text\. AWS Panorama does not store these files; they can only be retrieved when you register an appliance\. + +Camera stream credentials \(username and password\) are not encrypted at rest in the AWS Panorama service\. AWS Panorama stores stream credentials and sends them to the application with AWS IoT Greengrass\. + +The AWS Panorama Appliance sends log data to Amazon CloudWatch Logs\. CloudWatch Logs encrypts this data by default, and can be configured to use a customer managed key\. For more information, see [Encrypt log data in CloudWatch Logs using AWS KMS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) in the *Amazon CloudWatch Logs User Guide*\. \ No newline at end of file diff --git a/docs-source/security-iam.md b/docs-source/security-iam.md new file mode 100644 index 0000000..36dc548 --- /dev/null +++ b/docs-source/security-iam.md @@ -0,0 +1,98 @@ +# Identity and access management for AWS Panorama + +AWS Identity and Access Management \(IAM\) is an AWS service that helps an administrator securely control access to AWS resources\. IAM administrators control who can be *authenticated* \(signed in\) and *authorized* \(have permissions\) to use AWS Panorama resources\. IAM is an AWS service that you can use with no additional charge\. + +**Topics** ++ [Audience](#security_iam_audience) ++ [Authenticating with identities](#security_iam_authentication) ++ [Managing access using policies](#security_iam_access-manage) ++ [How AWS Panorama works with IAM](security_iam_service-with-iam.md) ++ [AWS Panorama identity\-based policy examples](security_iam_id-based-policy-examples.md) ++ [Troubleshooting AWS Panorama identity and access](security_iam_troubleshoot.md) + +## Audience + +How you use AWS Identity and Access Management \(IAM\) differs, depending on the work that you do in AWS Panorama\. + +**Service user** – If you use the AWS Panorama service to do your job, then your administrator provides you with the credentials and permissions that you need\. As you use more AWS Panorama features to do your work, you might need additional permissions\. Understanding how access is managed can help you request the right permissions from your administrator\. If you cannot access a feature in AWS Panorama, see [Troubleshooting AWS Panorama identity and access](security_iam_troubleshoot.md)\. + +**Service administrator** – If you're in charge of AWS Panorama resources at your company, you probably have full access to AWS Panorama\. It's your job to determine which AWS Panorama features and resources your employees should access\. You must then submit requests to your IAM administrator to change the permissions of your service users\. Review the information on this page to understand the basic concepts of IAM\. To learn more about how your company can use IAM with AWS Panorama, see [How AWS Panorama works with IAM](security_iam_service-with-iam.md)\. + +**IAM administrator** – If you're an IAM administrator, you might want to learn details about how you can write policies to manage access to AWS Panorama\. To view example AWS Panorama identity\-based policies that you can use in IAM, see [AWS Panorama identity\-based policy examples](security_iam_id-based-policy-examples.md)\. + +## Authenticating with identities + +Authentication is how you sign in to AWS using your identity credentials\. For more information about signing in using the AWS Management Console, see [Signing in to the AWS Management Console as an IAM user or root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/console.html) in the *IAM User Guide*\. + +You must be *authenticated* \(signed in to AWS\) as the AWS account root user, an IAM user, or by assuming an IAM role\. You can also use your company's single sign\-on authentication or even sign in using Google or Facebook\. In these cases, your administrator previously set up identity federation using IAM roles\. When you access AWS using credentials from another company, you are assuming a role indirectly\. + +To sign in directly to the [AWS Management Console](https://console.aws.amazon.com/), use your password with your root user email address or your IAM user name\. You can access AWS programmatically using your root user or IAM users access keys\. AWS provides SDK and command line tools to cryptographically sign your request using your credentials\. If you don't use AWS tools, you must sign the request yourself\. Do this using *Signature Version 4*, a protocol for authenticating inbound API requests\. For more information about authenticating requests, see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *AWS General Reference*\. + +Regardless of the authentication method that you use, you might also be required to provide additional security information\. For example, AWS recommends that you use multi\-factor authentication \(MFA\) to increase the security of your account\. To learn more, see [Using multi\-factor authentication \(MFA\) in AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html) in the *IAM User Guide*\. + +### AWS account root user + + When you first create an AWS account, you begin with a single sign\-in identity that has complete access to all AWS services and resources in the account\. This identity is called the AWS account *root user* and is accessed by signing in with the email address and password that you used to create the account\. We strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones\. Instead, adhere to the [best practice of using the root user only to create your first IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users)\. Then securely lock away the root user credentials and use them to perform only a few account and service management tasks\. + +### IAM users and groups + +An *[IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)* is an identity within your AWS account that has specific permissions for a single person or application\. An IAM user can have long\-term credentials such as a user name and password or a set of access keys\. To learn how to generate access keys, see [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) in the *IAM User Guide*\. When you generate access keys for an IAM user, make sure you view and securely save the key pair\. You cannot recover the secret access key in the future\. Instead, you must generate a new access key pair\. + +An [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) is an identity that specifies a collection of IAM users\. You can't sign in as a group\. You can use groups to specify permissions for multiple users at a time\. Groups make permissions easier to manage for large sets of users\. For example, you could have a group named *IAMAdmins* and give that group permissions to administer IAM resources\. + +Users are different from roles\. A user is uniquely associated with one person or application, but a role is intended to be assumable by anyone who needs it\. Users have permanent long\-term credentials, but roles provide temporary credentials\. To learn more, see [When to create an IAM user \(instead of a role\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html#id_which-to-choose) in the *IAM User Guide*\. + +### IAM roles + +An *[IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)* is an identity within your AWS account that has specific permissions\. It is similar to an IAM user, but is not associated with a specific person\. You can temporarily assume an IAM role in the AWS Management Console by [switching roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html)\. You can assume a role by calling an AWS CLI or AWS API operation or by using a custom URL\. For more information about methods for using roles, see [Using IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) in the *IAM User Guide*\. + +IAM roles with temporary credentials are useful in the following situations: ++ **Temporary IAM user permissions** – An IAM user can assume an IAM role to temporarily take on different permissions for a specific task\. ++ **Federated user access** – Instead of creating an IAM user, you can use existing identities from AWS Directory Service, your enterprise user directory, or a web identity provider\. These are known as *federated users*\. AWS assigns a role to a federated user when access is requested through an [identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)\. For more information about federated users, see [Federated users and roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles) in the *IAM User Guide*\. ++ **Cross\-account access** – You can use an IAM role to allow someone \(a trusted principal\) in a different account to access resources in your account\. Roles are the primary way to grant cross\-account access\. However, with some AWS services, you can attach a policy directly to a resource \(instead of using a role as a proxy\)\. To learn the difference between roles and resource\-based policies for cross\-account access, see [How IAM roles differ from resource\-based policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_compare-resource-policies.html) in the *IAM User Guide*\. ++ **Cross\-service access** – Some AWS services use features in other AWS services\. For example, when you make a call in a service, it's common for that service to run applications in Amazon EC2 or store objects in Amazon S3\. A service might do this using the calling principal's permissions, using a service role, or using a service\-linked role\. + + **Principal permissions** – When you use an IAM user or role to perform actions in AWS, you are considered a principal\. Policies grant permissions to a principal\. When you use some services, you might perform an action that then triggers another action in a different service\. In this case, you must have permissions to perform both actions\. To see whether an action requires additional dependent actions in a policy, see [Actions, Resources, and Condition Keys for AWS Panorama](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awspanorama.html) in the *Service Authorization Reference*\. + + **Service role** – A service role is an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a service assumes to perform actions on your behalf\. Service roles provide access only within your account and cannot be used to grant access to services in other accounts\. An IAM administrator can create, modify, and delete a service role from within IAM\. For more information, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*\. + + **Service\-linked role** – A service\-linked role is a type of service role that is linked to an AWS service\. The service can assume the role to perform an action on your behalf\. Service\-linked roles appear in your IAM account and are owned by the service\. An IAM administrator can view, but not edit the permissions for service\-linked roles\. ++ **Applications running on Amazon EC2** – You can use an IAM role to manage temporary credentials for applications that are running on an EC2 instance and making AWS CLI or AWS API requests\. This is preferable to storing access keys within the EC2 instance\. To assign an AWS role to an EC2 instance and make it available to all of its applications, you create an instance profile that is attached to the instance\. An instance profile contains the role and enables programs that are running on the EC2 instance to get temporary credentials\. For more information, see [Using an IAM role to grant permissions to applications running on Amazon EC2 instances](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) in the *IAM User Guide*\. + +To learn whether to use IAM roles or IAM users, see [When to create an IAM role \(instead of a user\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html#id_which-to-choose_role) in the *IAM User Guide*\. + +## Managing access using policies + +You control access in AWS by creating policies and attaching them to IAM identities or AWS resources\. A policy is an object in AWS that, when associated with an identity or resource, defines their permissions\. You can sign in as the root user or an IAM user, or you can assume an IAM role\. When you then make a request, AWS evaluates the related identity\-based or resource\-based policies\. Permissions in the policies determine whether the request is allowed or denied\. Most policies are stored in AWS as JSON documents\. For more information about the structure and contents of JSON policy documents, see [Overview of JSON policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json) in the *IAM User Guide*\. + +Administrators can use AWS JSON policies to specify who has access to what\. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**\. + +Every IAM entity \(user or role\) starts with no permissions\. In other words, by default, users can do nothing, not even change their own password\. To give a user permission to do something, an administrator must attach a permissions policy to a user\. Or the administrator can add the user to a group that has the intended permissions\. When an administrator gives permissions to a group, all users in that group are granted those permissions\. + +IAM policies define permissions for an action regardless of the method that you use to perform the operation\. For example, suppose that you have a policy that allows the `iam:GetRole` action\. A user with that policy can get role information from the AWS Management Console, the AWS CLI, or the AWS API\. + +### Identity\-based policies + +Identity\-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role\. These policies control what actions users and roles can perform, on which resources, and under what conditions\. To learn how to create an identity\-based policy, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*\. + +Identity\-based policies can be further categorized as *inline policies* or *managed policies*\. Inline policies are embedded directly into a single user, group, or role\. Managed policies are standalone policies that you can attach to multiple users, groups, and roles in your AWS account\. Managed policies include AWS managed policies and customer managed policies\. To learn how to choose between a managed policy or an inline policy, see [Choosing between managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#choosing-managed-or-inline) in the *IAM User Guide*\. + +### Resource\-based policies + +Resource\-based policies are JSON policy documents that you attach to a resource\. Examples of resource\-based policies are IAM *role trust policies* and Amazon S3 *bucket policies*\. In services that support resource\-based policies, service administrators can use them to control access to a specific resource\. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions\. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource\-based policy\. Principals can include accounts, users, roles, federated users, or AWS services\. + +Resource\-based policies are inline policies that are located in that service\. You can't use AWS managed policies from IAM in a resource\-based policy\. + +### Access control lists \(ACLs\) + +Access control lists \(ACLs\) control which principals \(account members, users, or roles\) have permissions to access a resource\. ACLs are similar to resource\-based policies, although they do not use the JSON policy document format\. + +Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs\. To learn more about ACLs, see [Access control list \(ACL\) overview](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html) in the *Amazon Simple Storage Service Developer Guide*\. + +### Other policy types + +AWS supports additional, less\-common policy types\. These policy types can set the maximum permissions granted to you by the more common policy types\. ++ **Permissions boundaries** – A permissions boundary is an advanced feature in which you set the maximum permissions that an identity\-based policy can grant to an IAM entity \(IAM user or role\)\. You can set a permissions boundary for an entity\. The resulting permissions are the intersection of entity's identity\-based policies and its permissions boundaries\. Resource\-based policies that specify the user or role in the `Principal` field are not limited by the permissions boundary\. An explicit deny in any of these policies overrides the allow\. For more information about permissions boundaries, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*\. ++ **Service control policies \(SCPs\)** – SCPs are JSON policies that specify the maximum permissions for an organization or organizational unit \(OU\) in AWS Organizations\. AWS Organizations is a service for grouping and centrally managing multiple AWS accounts that your business owns\. If you enable all features in an organization, then you can apply service control policies \(SCPs\) to any or all of your accounts\. The SCP limits permissions for entities in member accounts, including each AWS account root user\. For more information about Organizations and SCPs, see [How SCPs work](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_about-scps.html) in the *AWS Organizations User Guide*\. ++ **Session policies** – Session policies are advanced policies that you pass as a parameter when you programmatically create a temporary session for a role or federated user\. The resulting session's permissions are the intersection of the user or role's identity\-based policies and the session policies\. Permissions can also come from a resource\-based policy\. An explicit deny in any of these policies overrides the allow\. For more information, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*\. + +### Multiple policy types + +When multiple types of policies apply to a request, the resulting permissions are more complicated to understand\. To learn how AWS determines whether to allow a request when multiple policy types are involved, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*\. \ No newline at end of file diff --git a/docs-source/security-infrastructure.md b/docs-source/security-infrastructure.md new file mode 100644 index 0000000..a444233 --- /dev/null +++ b/docs-source/security-infrastructure.md @@ -0,0 +1,7 @@ +# Infrastructure security in AWS Panorama + +As a managed service, AWS Panorama is protected by the AWS global network security procedures that are described in the [Amazon Web Services: Overview of security processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) whitepaper\. + +You use AWS published API calls to access AWS Panorama through the network\. Clients must support Transport Layer Security \(TLS\) 1\.2 or later\. Clients must also support cipher suites with perfect forward secrecy \(PFS\) such as Ephemeral Diffie\-Hellman \(DHE\) or Elliptic Curve Ephemeral Diffie\-Hellman \(ECDHE\)\. Most modern systems such as Java 7 and later support these modes\. + +Additionally, requests must be signed by using an access key ID and a secret access key that is associated with an IAM principal\. Or you can use the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) \(AWS STS\) to generate temporary security credentials to sign requests\. \ No newline at end of file diff --git a/docs-source/security-network.md b/docs-source/security-network.md new file mode 100644 index 0000000..b3cd757 --- /dev/null +++ b/docs-source/security-network.md @@ -0,0 +1,47 @@ +# Network security for AWS Panorama + +This section provides information on network security for AWS Panorama, including network configuration for the AWS Panorama Appliance Developer Kit and AWS Panorama Appliance network activity\. + +## Network security for the AWS Panorama Appliance Developer Kit + + The AWS Panorama Appliance Developer Kit helps you develop a proof of concept for your computer vision applications\. We recommend using the AWS Panorama Appliance Developer Kit only in a test environment\. We don't recommend simultaneously connecting AWS Panorama to a sensitive or isolated network and an internet connected network\. Be careful if your configuration allows the AWS Panorama Appliance Developer Kit to act as a bridge to a sensitive IP camera network\. + +You are responsible for the following: ++ The physical and logical network security of the AWS Panorama Appliance Developer Kit\. ++ Securely operating the network\-attached cameras when you use the AWS Panorama Appliance Developer Kit\. ++ Keeping the AWS Panorama Appliance and camera software updated\. ++ Complying with any applicable laws or regulations associated with the content of the videos and images you gather from your production environments, including those related to privacy\. + +### Network configuration for testing with non\-production data \(most secure\) + + For testing with non\-production data with the AWS Panorama Appliance Developer Kit, we recommend that you use a local IP camera and physically connect the camera to AWS Panorama Appliance using an Ethernet connection\. Then use a subnet \(isolated from your production environment\) to connect the AWS Panorama Appliance to the AWS Cloud\. + + If a physical Ethernet connection is not possible, you can instead connect the IP camera to a hub on your subnet \(isolated from your production environment\), and use a subnet to connect the AWS Panorama Appliance Developer Kit to the AWS Cloud\. + +### Network configuration for testing with production data \(less secure\) + + If you need to test production data with the AWS Panorama Appliance Developer Kit, you can use a separate Virtual Local Area Network \(VLAN\) and restrict access to the VLAN only to the camera and the AWS Panorama Appliance Developer Kit\. Use a firewall to limit incoming and outgoing traffic only to the AWS Cloud endpoints necessary for operation\. This ensures there is a one\-way communication only from the camera to the AWS Panorama Appliance Developer Kit, and isolates your test environment from any other VMS and any production environment\. + +## AWS Panorama Appliance network activity + + The AWS Panorama Appliance connects to your cameras over a local Ethernet connection and uses TLS on port 443 to connect to the AWS Cloud\. The endpoint host name is not fixed, but the endpoint format is \*\.iot\.\.amazonaws\.com\. For more information see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html) in the *AWS General Reference guide*\. + +AWS Panorama uses your network for the following AWS Panorama Appliance functions\. + +**Application deployment** + +AWS Panorama uses your network to connect to AWS IoT Greengrass and uses remote AWS IoT jobs to deploy your application to your AWS Panorama Appliance\. The AWS IoT Greengrass core manages the network activity of AWS IoT Greengrass\. For more information see [Configure the AWS IoT Greengrass core](https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-core.html)\. + +**Camera identification and connection** + + When you add camera streams in Automatic connection mode, the AWS Panorama Appliance uses a remote AWS IoT job to scan your network and identify ONVIF compliant cameras on your subnet\. The AWS Panorama Appliance then uses Real\-time Streaming Protocol \(RTSP\) to connect to the video streams from IP cameras on your network\. For initial setup, you must use RTSTP on port 554 for streaming\. After initial setup, RTSP can use additional ports\. + + For more information see the RTSP [RFC 2326](https://tools.ietf.org/html/rfc2326)\. + +**Continuous monitoring** + +AWS Panorama uses a remote AWS IoT job to monitor the network status and software version on your AWS Panorama Appliance\. The job runs every 30 seconds to determine whether your AWS Panorama Appliance is online and using the latest software\. + +**AWS Panorama Appliance updates** + +When you request a software update or provide new credentials or configurations, AWS Panorama uses a remote AWS IoT job to send the updates to your AWS Panorama Appliance over the network\. \ No newline at end of file diff --git a/docs-source/security-resilience.md b/docs-source/security-resilience.md new file mode 100644 index 0000000..c216476 --- /dev/null +++ b/docs-source/security-resilience.md @@ -0,0 +1,5 @@ +# Resilience in AWS Panorama + +The AWS global infrastructure is built around AWS Regions and Availability Zones\. AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low\-latency, high\-throughput, and highly redundant networking\. With Availability Zones, you can design and operate applications and databases that automatically fail over between Availability Zones without interruption\. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures\. + +The list of available services varies by AWS Region\. For more information about AWS Regions and Availability Zones, see [AWS global infrastructure](http://aws.amazon.com/about-aws/global-infrastructure/)\. \ No newline at end of file diff --git a/docs-source/security_iam_id-based-policy-examples.md b/docs-source/security_iam_id-based-policy-examples.md new file mode 100644 index 0000000..8172c98 --- /dev/null +++ b/docs-source/security_iam_id-based-policy-examples.md @@ -0,0 +1,63 @@ +# AWS Panorama identity\-based policy examples + +By default, IAM users and roles don't have permission to create or modify AWS Panorama resources\. They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API\. An IAM administrator must create IAM policies that grant users and roles permission to perform specific API operations on the specified resources they need\. The administrator must then attach those policies to the IAM users or groups that require those permissions\. + +To learn how to create an IAM identity\-based policy using these example JSON policy documents, see [Creating policies on the JSON tab](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-json-editor) in the *IAM User Guide*\. + +**Topics** ++ [Policy best practices](#security_iam_service-with-iam-policy-best-practices) ++ [Using the AWS Panorama console](#security_iam_id-based-policy-examples-console) ++ [Allow users to view their own permissions](#security_iam_id-based-policy-examples-view-own-permissions) + +## Policy best practices + +Identity\-based policies are very powerful\. They determine whether someone can create, access, or delete AWS Panorama resources in your account\. These actions can incur costs for your AWS account\. When you create or edit identity\-based policies, follow these guidelines and recommendations: ++ **Get started using AWS managed policies** – To start using AWS Panorama quickly, use AWS managed policies to give your employees the permissions they need\. These policies are already available in your account and are maintained and updated by AWS\. For more information, see [Get started using permissions with AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-use-aws-defined-policies) in the *IAM User Guide*\. ++ **Grant least privilege** – When you create custom policies, grant only the permissions required to perform a task\. Start with a minimum set of permissions and grant additional permissions as necessary\. Doing so is more secure than starting with permissions that are too lenient and then trying to tighten them later\. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) in the *IAM User Guide*\. ++ **Enable MFA for sensitive operations** – For extra security, require IAM users to use multi\-factor authentication \(MFA\) to access sensitive resources or API operations\. For more information, see [Using multi\-factor authentication \(MFA\) in AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html) in the *IAM User Guide*\. ++ **Use policy conditions for extra security** – To the extent that it's practical, define the conditions under which your identity\-based policies allow access to a resource\. For example, you can write conditions to specify a range of allowable IP addresses that a request must come from\. You can also write conditions to allow requests only within a specified date or time range, or to require the use of SSL or MFA\. For more information, see [IAM JSON policy elements: Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) in the *IAM User Guide*\. + +## Using the AWS Panorama console + +To access the AWS Panorama console, you must have a minimum set of permissions\. These permissions must allow you to list and view details about the AWS Panorama resources in your AWS account\. If you create an identity\-based policy that is more restrictive than the minimum required permissions, the console won't function as intended for entities \(IAM users or roles\) with that policy\. + +For more information, see [Identity\-based IAM policies for AWS Panorama](permissions-roles.md) + +## Allow users to view their own permissions + +This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity\. This policy includes permissions to complete this action on the console or programmatically using the AWS CLI or AWS API\. + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "ViewOwnUserInfo", + "Effect": "Allow", + "Action": [ + "iam:GetUserPolicy", + "iam:ListGroupsForUser", + "iam:ListAttachedUserPolicies", + "iam:ListUserPolicies", + "iam:GetUser" + ], + "Resource": ["arn:aws:iam::*:user/${aws:username}"] + }, + { + "Sid": "NavigateInConsole", + "Effect": "Allow", + "Action": [ + "iam:GetGroupPolicy", + "iam:GetPolicyVersion", + "iam:GetPolicy", + "iam:ListAttachedGroupPolicies", + "iam:ListGroupPolicies", + "iam:ListPolicyVersions", + "iam:ListPolicies", + "iam:ListUsers" + ], + "Resource": "*" + } + ] +} +``` \ No newline at end of file diff --git a/docs-source/security_iam_service-with-iam.md b/docs-source/security_iam_service-with-iam.md new file mode 100644 index 0000000..97e8362 --- /dev/null +++ b/docs-source/security_iam_service-with-iam.md @@ -0,0 +1,5 @@ +# How AWS Panorama works with IAM + +Before you use IAM to manage access to AWS Panorama, you should understand what IAM features are available to use with AWS Panorama\. To get a high\-level view of how AWS Panorama and other AWS services work with IAM, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*\. + +For an overview of permissions, policies, and roles as they are used by AWS Panorama, see [AWS Panorama permissions](panorama-permissions.md)\. \ No newline at end of file diff --git a/docs-source/security_iam_troubleshoot.md b/docs-source/security_iam_troubleshoot.md new file mode 100644 index 0000000..cf8d4f2 --- /dev/null +++ b/docs-source/security_iam_troubleshoot.md @@ -0,0 +1,64 @@ +# Troubleshooting AWS Panorama identity and access + +Use the following information to help you diagnose and fix common issues that you might encounter when working with AWS Panorama and IAM\. + +**Topics** ++ [I am not authorized to perform an action in AWS Panorama](#security_iam_troubleshoot-no-permissions) ++ [I am not authorized to perform iam:PassRole](#security_iam_troubleshoot-passrole) ++ [I want to view my access keys](#security_iam_troubleshoot-access-keys) ++ [I'm an administrator and want to allow others to access AWS Panorama](#security_iam_troubleshoot-admin-delegate) ++ [I want to allow people outside of my AWS account to access my AWS Panorama resources](#security_iam_troubleshoot-cross-account-access) + +## I am not authorized to perform an action in AWS Panorama + +If the AWS Management Console tells you that you're not authorized to perform an action, then you must contact your administrator for assistance\. Your administrator is the person that provided you with your user name and password\. + +The following example error occurs when the `mateojackson` IAM user tries to use the console to view details about a function but does not have `panorama:DescribeAppliance` permissions\. + +``` +User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: panorama:DescribeAppliance on resource: my-appliance +``` + +In this case, Mateo asks his administrator to update his policies to allow him to access the `my-appliance` resource using the `panorama:DescribeAppliance` action\. + +## I am not authorized to perform iam:PassRole + +If you receive an error that you're not authorized to perform the `iam:PassRole` action, then you must contact your administrator for assistance\. Your administrator is the person that provided you with your user name and password\. Ask that person to update your policies to allow you to pass a role to AWS Panorama\. + +Some AWS services allow you to pass an existing role to that service, instead of creating a new service role or service\-linked role\. To do this, you must have permissions to pass the role to the service\. + +The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in AWS Panorama\. However, the action requires the service to have permissions granted by a service role\. Mary does not have permissions to pass the role to the service\. + +``` +User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole +``` + +In this case, Mary asks her administrator to update her policies to allow her to perform the `iam:PassRole` action\. + +## I want to view my access keys + +After you create your IAM user access keys, you can view your access key ID at any time\. However, you can't view your secret access key again\. If you lose your secret key, you must create a new access key pair\. + +Access keys consist of two parts: an access key ID \(for example, `AKIAIOSFODNN7EXAMPLE`\) and a secret access key \(for example, `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`\)\. Like a user name and password, you must use both the access key ID and secret access key together to authenticate your requests\. Manage your access keys as securely as you do your user name and password\. + +**Important** + Do not provide your access keys to a third party, even to help [find your canonical user ID](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html#FindingCanonicalId)\. By doing this, you might give someone permanent access to your account\. + +When you create an access key pair, you are prompted to save the access key ID and secret access key in a secure location\. The secret access key is available only at the time you create it\. If you lose your secret access key, you must add new access keys to your IAM user\. You can have a maximum of two access keys\. If you already have two, you must delete one key pair before creating a new one\. To view instructions, see [Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) in the *IAM User Guide*\. + +## I'm an administrator and want to allow others to access AWS Panorama + +To allow others to access AWS Panorama, you must create an IAM entity \(user or role\) for the person or application that needs access\. They will use the credentials for that entity to access AWS\. You must then attach a policy to the entity that grants them the correct permissions in AWS Panorama\. + +To get started right away, see [Creating your first IAM delegated user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-delegated-user.html) in the *IAM User Guide*\. + +## I want to allow people outside of my AWS account to access my AWS Panorama resources + +You can create a role that users in other accounts or people outside of your organization can use to access your resources\. You can specify who is trusted to assume the role\. For services that support resource\-based policies or access control lists \(ACLs\), you can use those policies to grant people access to your resources\. + +To learn more, consult the following: ++ To learn whether AWS Panorama supports these features, see [How AWS Panorama works with IAM](security_iam_service-with-iam.md)\. ++ To learn how to provide access to your resources across AWS accounts that you own, see [Providing access to an IAM user in another AWS account that you own](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html) in the *IAM User Guide*\. ++ To learn how to provide access to your resources to third\-party AWS accounts, see [Providing access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *IAM User Guide*\. ++ To learn how to provide access through identity federation, see [Providing access to externally authenticated users \(identity federation\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*\. ++ To learn the difference between using roles and resource\-based policies for cross\-account access, see [How IAM roles differ from resource\-based policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_compare-resource-policies.html) in the *IAM User Guide*\. \ No newline at end of file diff --git a/resources/model-compatibility.md b/resources/model-compatibility.md new file mode 100644 index 0000000..9f4422a --- /dev/null +++ b/resources/model-compatibility.md @@ -0,0 +1,136 @@ +# Model compatibility + +AWS Panorama uses Amazon SageMaker Neo to compile your machine learning models for AWS Panorama Appliances. Here is a list of commonly used computer vision models that have been tested with Amazon SageMaker Neo for compilation. You can use these models for learning and demo purposes or for developing your machine learning applications. + +## Darknet + +- resnet50 +- yolov2 +- yolov2_tiny +- yolov3_416 +- yolov3_tiny + +## GluonCV (MXnet) + +- DenseNet201 +- GoogLeNet +- InceptionV3 +- MobileNet0.75 +- MobileNet1.0 +- MobileNetV2_0.5 +- MobileNetV2_1.0 +- MobileNetV3_Large +- MobileNetV3_Small +- ResNeSt50 +- ResNet18_v1 +- ResNet18_v2 +- ResNet50_v1 +- ResNet50_v2 +- SENet_154 +- SE_ResNext50_32x4d +- SqueezeNet1.0 +- SqueezeNet1.1 +- Xception +- darknet53 +- resnet18_v1b_0.89 +- resnet50_v1d_0.11 +- resnet50_v1d_0.86 +- ssd_512_mobilenet1.0_coco +- ssd_512_mobilenet1.0_voc +- ssd_512_resnet50_v1_coco +- yolo3_darknet53_coco +- yolo3_mobilenet1.0_coco + +## Keras + +- DenseNet121 +- DenseNet201 +- mobilenet_v1 +- mobilenet_v2 +- resnet50_v1 +- resnet50_v2 + +## ONNX + +- mobilenetv2-1.0 +- resnet152v1 +- resnet18v1 +- resnet18v2 +- resnet50v1 +- resnet50v2 +- squeezenet1.1 + +## PyTorch + +- densenet121 +- resnet152 +- resnet18 +- resnet50 +- squeezenet1.0 +- squeezenet1.1 +- vgg16_bn +- yolov4 +- faster r-cnn resnet-50 fpn +- mask r-cnn resnet-50 fpn + +## TensorFlow + +- DenseNet121 +- DenseNet201 +- MobileNet +- MobileNetV2 +- NASNetLarge +- NASNetMobile +- ResNet101 +- ResNet101V2 +- ResNet152 +- ResNet152V2 +- ResNet50 +- ResNet50V2 +- Xception +- mobilenet100_v1 +- mobilenet100_v2.0 +- mobilenet130_v2 +- mobilenet140_v2 +- resnet50_v1.5 +- resnet50_v2 +- squeezenet +- faster_rcnn_inception_resnet_v2_atrous_coco +- faster_rcnn_inception_resnet_v2_atrous_lowproposals_coco +- faster_rcnn_inception_v2_coco +- faster_rcnn_nas +- faster_rcnn_nas_lowproposals_coco +- faster_rcnn_resnet101_coco +- faster_rcnn_resnet101_lowproposals_coco +- faster_rcnn_resnet50_coco +- faster_rcnn_resnet50_lowproposals_coco +- mask_rcnn_inception_resnet_v2_atrous_coco +- mask_rcnn_resnet101_atrous_coco +- mask_rcnn_resnet50_atrous_coco +- rfcn_resnet101_coco +- ssd_mobilenet_v1_0.75_depth_coco +- ssd_mobilenet_v1_0.75_depth_quantized_coco +- ssd_mobilenet_v1_coco +- ssd_mobilenet_v1_fpn_coco +- ssd_mobilenet_v1_ppn_coco +- ssd_mobilenet_v2_coco + +## TensorFlow-Lite + +- densenet_2018_04_27 +- inception_resnet_v2_2018_04_27 +- inception_v3_2018_04_27 +- mnasnet_0.5_224_09_07_2018 +- mnasnet_1.0_224_09_07_2018 +- mnasnet_1.3_224_09_07_2018 +- mobilenet_v1_0.25_128 +- mobilenet_v1_0.25_224 +- mobilenet_v1_0.5_128 +- mobilenet_v1_0.5_224 +- mobilenet_v1_0.75_128 +- mobilenet_v1_0.75_224 +- mobilenet_v1_1.0_128 +- mobilenet_v1_1.0_192 +- mobilenet_v2_1.0_224 +- resnet_v2_101 +- squeezenet_2018_04_27 diff --git a/sample-apps/aws-panorama-sample/1-create-bucket.sh b/sample-apps/aws-panorama-sample/1-create-bucket.sh new file mode 100755 index 0000000..590ef78 --- /dev/null +++ b/sample-apps/aws-panorama-sample/1-create-bucket.sh @@ -0,0 +1,5 @@ +#!/bin/bash +BUCKET_ID=$(dd if=/dev/random bs=8 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n') +BUCKET_NAME=aws-panorama-artifacts-$BUCKET_ID +echo $BUCKET_NAME > bucket-name.txt +aws s3 mb s3://$BUCKET_NAME diff --git a/sample-apps/aws-panorama-sample/2-deploy.sh b/sample-apps/aws-panorama-sample/2-deploy.sh new file mode 100755 index 0000000..a54a1a5 --- /dev/null +++ b/sample-apps/aws-panorama-sample/2-deploy.sh @@ -0,0 +1,5 @@ +#!/bin/bash +set -eo pipefail +ARTIFACT_BUCKET=$(cat bucket-name.txt) +aws cloudformation package --template-file template.yml --s3-bucket $ARTIFACT_BUCKET --output-template-file out.yml +aws cloudformation deploy --template-file out.yml --stack-name aws-panorama-sample --capabilities CAPABILITY_NAMED_IAM diff --git a/sample-apps/aws-panorama-sample/3-upload-model.sh b/sample-apps/aws-panorama-sample/3-upload-model.sh new file mode 100755 index 0000000..3aa8dcb --- /dev/null +++ b/sample-apps/aws-panorama-sample/3-upload-model.sh @@ -0,0 +1,10 @@ +#!/bin/bash +set -eo pipefail +BUCKET=$(cat bucket-name.txt) +MODEL_ARCHIVE=ssd_512_resnet50_v1_voc.tar.gz +if [ -f $MODEL_ARCHIVE ]; then + aws s3 cp $MODEL_ARCHIVE s3://$BUCKET + echo "Uploaded model: s3://$BUCKET/$MODEL_ARCHIVE" +else + echo "Model file not found: $MODEL_ARCHIVE" +fi diff --git a/sample-apps/aws-panorama-sample/4-get-configuration.sh b/sample-apps/aws-panorama-sample/4-get-configuration.sh new file mode 100755 index 0000000..23c8e5b --- /dev/null +++ b/sample-apps/aws-panorama-sample/4-get-configuration.sh @@ -0,0 +1,13 @@ +#!/bin/bash +set -eo pipefail +MODEL_NAME=aws-panorama-sample-model +MODEL_ARCHIVE=ssd_512_resnet50_v1_voc.tar.gz +BUCKET=$(cat bucket-name.txt) +MODEL_URI=s3://$BUCKET/$MODEL_ARCHIVE +VERSION=$(aws cloudformation describe-stack-resource --stack-name aws-panorama-sample --logical-resource-id version --query 'StackResourceDetail.PhysicalResourceId' --output text) +echo "FUNCTION VERSION ARN" +echo $VERSION +echo "MODEL NAME" +echo $MODEL_NAME +echo "MODEL OBJECT URI" +echo $MODEL_URI diff --git a/sample-apps/aws-panorama-sample/5-cleanup.sh b/sample-apps/aws-panorama-sample/5-cleanup.sh new file mode 100755 index 0000000..d3debd7 --- /dev/null +++ b/sample-apps/aws-panorama-sample/5-cleanup.sh @@ -0,0 +1,28 @@ +#!/bin/bash +set -eo pipefail +STACK=aws-panorama-sample +if [[ $# -eq 1 ]] ; then + STACK=$1 + echo "Deleting stack $STACK" +fi +FUNCTION=$(aws cloudformation describe-stack-resource --stack-name $STACK --logical-resource-id function --query 'StackResourceDetail.PhysicalResourceId' --output text) +aws cloudformation delete-stack --stack-name $STACK +echo "Deleted $STACK stack." + +if [ -f bucket-name.txt ]; then + ARTIFACT_BUCKET=$(cat bucket-name.txt) + if [[ ! $ARTIFACT_BUCKET =~ aws-panorama-artifacts-[a-z0-9]{16} ]] ; then + echo "Bucket was not created by this application. Skipping." + else + while true; do + read -p "Delete deployment artifacts and bucket ($ARTIFACT_BUCKET)? (y/n)" response + case $response in + [Yy]* ) aws s3 rb --force s3://$ARTIFACT_BUCKET; rm bucket-name.txt; break;; + [Nn]* ) break;; + * ) echo "Response must start with y or n.";; + esac + done + fi +fi + +rm -f out.yml out.json diff --git a/sample-apps/aws-panorama-sample/README.md b/sample-apps/aws-panorama-sample/README.md new file mode 100644 index 0000000..e832f36 --- /dev/null +++ b/sample-apps/aws-panorama-sample/README.md @@ -0,0 +1,64 @@ +# AWS Panorama sample application + +![Architecture](/sample-apps/aws-panorama-sample/images/sample-aws-panorama-sample.png) + +The project source includes function code and supporting resources: + +- `function` - A Python function. +- `template.yml` - An AWS CloudFormation template that creates an application. +- `1-create-bucket.sh`, `2-build-layer.sh`, etc. - Shell scripts that use the AWS CLI to deploy and manage the application. + +Use the following instructions to deploy the sample application. + +# Requirements +- [Python 3.7](https://www.python.org/downloads/) +- The Bash shell. For Linux and macOS, this is included by default. In Windows 10, you can install the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to get a Windows-integrated version of Ubuntu and Bash. +- [The AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) v1.17 or newer. + +# Setup +Download or clone this repository. + + $ git clone https://github.com/awsdocs/aws-panorama-developer-guide.git + $ cd aws-panorama-developer-guide/sample-apps/aws-panorama-sample + +To create a new bucket for deployment artifacts, run `1-create-bucket.sh`. + + aws-panorama-sample$ ./1-create-bucket.sh + make_bucket: aws-panorama-artifacts-a5e491dbb5b22e0d + +# Deploy +To deploy the application, run `2-deploy.sh`. + + aws-panorama-sample$ ./2-deploy.sh + Successfully packaged artifacts and wrote output template to file out.yml. + Waiting for changeset to be created.. + Waiting for stack create/update to complete + Successfully created/updated stack - aws-panorama-sample + +This script uses AWS CloudFormation to deploy the Lambda functions and an IAM role. If the AWS CloudFormation stack that contains the resources already exists, the script updates it with any changes to the template or function code. + +# Upload model + +Download the sample application's model and save it in the project directory. + +To upload the model to your S3 bucket, run `3-upload-model.sh`. + + aws-panorama-sample$ ./3-deploy.sh + +# Configure +To get configuration values, run `4-get-configuration.sh`. + + aws-panorama-sample$ ./4-get-configuration.sh + FUNCTION VERSION ARN + arn:aws:lambda:us-east-1:011685312445:function:aws-panorama-sample-function-WV4XS9NGCND7:1 + MODEL NAME + aws-panorama-sample-model + MODEL OBJECT URI + s3://aws-panorama-artifacts-672b1549d86aad55/ssd_512_resnet50_v1_voc.tar.gz + + + +# Cleanup +To delete the application stack and bucket, run `5-cleanup.sh`. + + aws-panorama-sample$ ./5-cleanup.sh diff --git a/sample-apps/aws-panorama-sample/code/lambda_function.py b/sample-apps/aws-panorama-sample/code/lambda_function.py new file mode 100644 index 0000000..095e732 --- /dev/null +++ b/sample-apps/aws-panorama-sample/code/lambda_function.py @@ -0,0 +1,148 @@ +import panoramasdk +import cv2 +import numpy as np +import boto3 + +HEIGHT = 512 +WIDTH = 512 + +class people_counter(panoramasdk.base): + + def interface(self): + return { + "parameters": + ( + ("float", "threshold", "Minimum confidence for display", 0.10), + ("model", "people_counter", "Name of the model in AWS Panorama", "aws-panorama-sample-model"), + ("int", "batch_size", "Model batch size", 1), + ("float", "person_index", "The index of the person class in the model's dataset", 14), + ), + "inputs": + ( + ("media[]", "video_in", "Camera input stream"), + ), + "outputs": + ( + ("media[video_in]", "video_out", "Camera output stream"), + ) + } + + + def init(self, parameters, inputs, outputs): + try: + self.threshold = parameters.threshold + self.person_index = parameters.person_index + self.threshold = parameters.threshold + self.frame_num = 0 + self.number_people = 0 + self.colours = np.random.rand(32, 3) + + print("Loading model: " + parameters.people_counter) + self.model = panoramasdk.model() + self.model.open(parameters.people_counter, 1) + + print("Creating input and output arrays") + class_info = self.model.get_output(0) + prob_info = self.model.get_output(1) + rect_info = self.model.get_output(2) + + self.class_array = np.empty(class_info.get_dims(), dtype=class_info.get_type()) + self.prob_array = np.empty(prob_info.get_dims(), dtype=prob_info.get_type()) + self.rect_array = np.empty(rect_info.get_dims(), dtype=rect_info.get_type()) + + print("Initialization complete") + return True + + except Exception as e: + print("Exception: {}".format(e)) + return False + + def preprocess(self, img): + resized = cv2.resize(img, (HEIGHT, WIDTH)) + mean = [0.485, 0.456, 0.406] + std = [0.229, 0.224, 0.225] + + img = resized.astype(np.float32) / 255. + img_a = img[:, :, 0] + img_b = img[:, :, 1] + img_c = img[:, :, 2] + + # Normalize data in each channel + img_a = (img_a - mean[0]) / std[0] + img_b = (img_b - mean[1]) / std[1] + img_c = (img_c - mean[2]) / std[2] + + # Put the channels back together + x1 = [[[], [], []]] + x1[0][0] = img_a + x1[0][1] = img_b + x1[0][2] = img_c + + x1 = np.asarray(x1) + return x1 + + def get_number_persons(self, class_data, prob_data): + # Filter out results beneath confidence threshold + person_indices = [i for i in range(len(class_data)) if int(class_data[i]) == self.person_index] + prob_person_indices = [i for i in person_indices if prob_data[i] >= self.threshold] + return prob_person_indices + + def entry(self, inputs, outputs): + self.frame_num += 1 + + for i in range(len(inputs.video_in)): + stream = inputs.video_in[i] + person_image = stream.image + stream.add_label('People detected: {}'.format(self.number_people), 0.8, 0.05) + + # Prepare the image and run inference + x1 = self.preprocess(person_image) + self.model.batch(0, x1) + self.model.flush() + resultBatchSet = self.model.get_result() + + # Process results + class_batch = resultBatchSet.get(0) + prob_batch = resultBatchSet.get(1) + rect_batch = resultBatchSet.get(2) + + class_batch.get(0, self.class_array) + prob_batch.get(0, self.prob_array) + rect_batch.get(0, self.rect_array) + + class_data = self.class_array[0] + prob_data = self.prob_array[0] + rect_data = self.rect_array[0] + + # Get indices of people classes + person_indices = self.get_number_persons(class_data,prob_data) + + try: + self.number_people = len(person_indices) + except: + self.number_people = 0 + + # Draw bounding boxes on output image + if self.number_people > 0: + for index in person_indices: + + left = np.clip(rect_data[index][0] / np.float(HEIGHT), 0, 1) + top = np.clip(rect_data[index][1] / np.float(WIDTH), 0, 1) + right = np.clip(rect_data[index][2] / np.float(HEIGHT), 0, 1) + bottom = np.clip(rect_data[index][3] / np.float(WIDTH), 0, 1) + + stream.add_rect(left, top, right, bottom) + stream.add_label(str(prob_data[index][0]), right, bottom) + # Add text + stream.add_label('People detected: {}'.format(self.number_people), 0.8, 0.05) + + self.model.release_result(resultBatchSet) + outputs.video_out[i] = stream + + return True + + +def main(): + people_counter().run() + +main() \ No newline at end of file diff --git a/sample-apps/aws-panorama-sample/template.yml b/sample-apps/aws-panorama-sample/template.yml new file mode 100644 index 0000000..ee37be6 --- /dev/null +++ b/sample-apps/aws-panorama-sample/template.yml @@ -0,0 +1,20 @@ +AWSTemplateFormatVersion: '2010-09-09' +Transform: 'AWS::Serverless-2016-10-31' +Description: An AWS Panorama application that counts people. +Resources: + function: + Type: AWS::Serverless::Function + Properties: + Handler: lambda_function.main + Runtime: python3.7 + CodeUri: code/. + Description: Count people + Timeout: 10 + # Function's role + Policies: + - AWSLambdaBasicExecutionRole + version: + Type: AWS::Lambda::Version + Properties: + FunctionName: !Ref function + Description: Sample application.