Initial release of AWS RoboMaker Person Detection sample application

NOTICE.txt

@@ -0,0 +1,4 @@
+Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+This product includes software developed by
+Amazon Technologies, Inc (http://www.amazon.com/).

README.md

@@ -1,7 +1,194 @@
-## AWS Robomaker Sample Application Persondetection
+# AWS RoboMaker Sample Application - Navigation and Person Detection
 
-Each of these packages is a sample application using ROS to demonstrate the use of the RoboMaker service and integration of other AWS services with ROS. 
+This application demonstrates the use of Amazon Rekognition to recognize people's faces
+and Amazon Polly to synthesize speech.
+
+
+_RoboMaker sample applications include third-party software licensed under open-source licenses and is provided for demonstration purposes only. Incorporation or use of RoboMaker sample applications in connection with your production workloads or a commercial products or devices may affect your legal rights or obligations under the applicable open-source licenses. Source code information can be found [here](https://s3.console.aws.amazon.com/s3/buckets/robomaker-applications-us-east-1-72fc243f9355/person-detection/?region=us-east-1)._
+
+
+![](docs/images/screenshot01.png)
+
+## Usage
+
+## Requirements
+
+- [ROS Kinetic](http://wiki.ros.org/kinetic/Installation/Ubuntu) - Other versions may work, however they have not been tested
+- [Colcon](https://colcon.readthedocs.io/en/released/user/installation.html) - Used for building and bundling the application. 
+
+## AWS Account Setup
+
+### Resources
+This sample application uses Amazon Kinesis and Amazon Rekognition to recognize faces. See [here](#architecture-details) for details.
+The easiest method is to reuse the resources create by the AWS RoboMaker sample application. To do that follow these steps:
+1. Sign in to the AWS RoboMaker console at https://us-west-2.console.aws.amazon.com/robomaker/home/.
+2. In the AWS RoboMaker console, expand Resources on the left and then select Sample applications.
+3. In the **Try RoboMaker sample applications** page, select **Navigation and person recognition** and then select Launch. 
+4. There will be a banner at the top of the page listing the number of resources that have been created. When all of the resources have been created
+it will open the **simulation job detail** page. At this point cancel the simulation job. This will not delete any of the resources.
+5. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation/ and find the stack with AWSRoboMakerPersonDetection in the name.
+6. Expand the **Parameters** tab and find the **LaunchId** Key. 
+7. In the runtime environment for the robot application set the `LAUNCH_ID` environmental variable to the **LaunchId** value from CloudFormation.
+   In AWS RoboMaker the environmental variable can be set as an option when running a simulation job. 
+   In a Linux environment this can be accomplisehd with `export LAUNCH_ID=<value>`
+8. When the robot application is run the launch files will use the `LAUNCH_ID` to connect to the correct Kinesis data stream and Kinesis video stream.
+
+When setting up resources using the above method new faces can be added to Rekognition with the following steps:
+1. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation/ and find the stack with AWSRoboMakerPersonDetection in the name.
+2. Expand the **Resources** tab and find the Physical ID of the Amazon S3 bucket with the Logical ID **BundlesBucket**.
+3. Copy the image into the **photos** folder of the bucket with the following command
+```bash
+aws s3 cp path/to/image s3://<physical_id>/photos/persons_name.png
+```
+
+If you'd like more detailed control over the resources follow the instructions here: https://docs.aws.amazon.com/rekognition/latest/dg/recognize-faces-in-a-video-stream.html.
+Make sure that the names of the Kinesis video stream and data stream match those in src/person_detection_robot/launch/kinesis.launch.
+
+### Permissions
+
+To publish to Amazon CloudWatch Metrics and Logs the IAM user configured in the environment in which the node is running
+will need the following permissions:
+ ```
+   logs:PutLogEvents
+   logs:DescribeLogStreams 
+   logs:CreateLogStream 
+   logs:CreateLogGroup
+```
+For more information about the CloudWatch Metrics node see here: https://github.com/aws-robotics/cloudwatchmetrics-ros1
+
+For more information about the CloudWatch Logs node see here: https://github.com/aws-robotics/cloudwatchlogs-ros1
+
+
+To use the Kinesis node you will need an IAM user with the following permissions:
+ ```
+  kinesisvideo:CreateStream
+  kinesisvideo:TagStream
+  kinesisvideo:DescribeStream
+  kinesisvideo:GetDataEndpoint
+  kinesisvideo:PutMedia
+  kinesis:ListShards
+  kinesis:GetShardIterator
+  kinesis:GetRecords
+  ```
+For more information on the Amazon Kinesis node see here: https://github.com/aws-robotics/kinesisvideo-ros1  
+
+To use the Polly node you will need an IAM user with the following permissions:
+```
+  polly:SynthesizeSpeech
+```
+ For more information on the Amazon Polly node see here https://github.com/aws-robotics/tts-ros1
+
+Information about attaching permissions to an IAM user can be found here: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html
+
+Information about configuring AWS credentials can be found here: https://docs-aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-multiple-profiles
+
+
+## Build
+
+### Pre-build commands
+
+```bash
+sudo apt-get update
+rosdep update
+```
+
+### Robot
+
+```bash
+cd robot_ws
+rosws update
+rosdep install --from-paths src --ignore-src -r -y
+colcon build
+```
+
+### Simulation
+
+```
+cd simulation_ws
+rosws update
+rosdep install --from-paths src --ignore-src -r -y
+colcon build
+```
+
+## Run
+
+Launch the application with the following commands:
+
+- *Running Robot Application on a Robot*
+    ```bash
+    source robot_ws/install/local_setup.sh
+    roslaunch person_detection_robot deploy_person_detection.launch
+    ```
+
+- *Running Robot Application Elsewhere*
+    ```bash
+    source robot_ws/install/local_setup.sh
+    roslaunch person_detection_robot person_detection.launch
+    ```
+
+- *Running Simulation Application*
+    ```bash
+    source simulation_ws/install/local_setup.sh
+    TURTLEBOT3_MODEL=waffle_pi roslaunch person_detection_simulation [command]
+    ```
+    There are two simulation launch commands:
+    - `small_house.launch` - A world with a kitchen, bedroom and living areas. The Turtlebot3 spawned is stationary waiting commands.
+    - `small_house_turtlebot_navigation.launch` - A small house with TB3 autonomously navigating to goal points on a route.
+
+## Using this sample with RoboMaker
+
+You first need to install colcon-ros-bundle. Python 3.5 or above is required. 
+
+```bash
+pip3 install colcon-ros-bundle
+```
+
+After colcon-ros-bundle is installed you need to build your robot or simulation, then you can bundle with:
+
+```bash
+# Bundling Robot Application
+cd robot_ws
+source install/local_setup.sh
+colcon bundle
+
+# Bundling Simulation Application
+cd simulation_ws
+source install/local_setup.sh
+colcon bundle
+```
+
+This produces the artifacts `robot_ws/build/output.tar.gz` and `simulation_ws/build/output.tar.gz` respectively. 
+
+You'll need to upload these to an s3 bucket, then you can use these files to 
+[create a robot application](https://docs.aws.amazon.com/robomaker/create-robot-application.html),  
+[create a simulation application](https://docs.aws.amazon.com/robomaker/create-simulation-application.html), 
+and [create a simulation job](https://docs.aws.amazon.com/robomaker/create-simulation-job.html) in RoboMaker.
+
+## Architecture Details
+![ArchitectureDiagram](docs/images/personDetectionDiagram.png)
+
+## AWS ROS Packages used by this Sample
+
+- RoboMakerUtils-Common
+- RobomakerUtils-ROS1
+- CloudWatch-Common
+- CloudWatchLogs-ROS1
+- CloudWatchMetrics-ROS1
+- HealthMetricsCollector-ROS1
+- KinesisVideo-Common
+- KinesisVideo-ROS1
+- KinesisVideoEncoder-Common
+- KinesisVideoEncoder-ROS1
+- MonitoringMessages-ROS1
+- TTS-ROS1
+
+
+## License
+
+MIT-0 - See LICENSE.txt for further information
+
+## How to Contribute
+
+Create issues and pull requests against this Repository on Github
 
-## License Summary
 
-This sample code is made available under a modified MIT license. See the LICENSE file.

roboMakerSettings.json

@@ -0,0 +1,104 @@
+{
+   "runConfigurations":[
+      {
+         "id":"PersonDetection_Cfg01",
+         "name":"PersonDetection Robot",
+         "type":"colcon build",
+         "cfg":{
+            "workingDir":"./PersonDetection/robot_ws",
+            "cmdArgs":""
+         }
+      },
+      {
+         "id":"PersonDetection_Cfg02",
+         "name":"PersonDetection Robot",
+         "type":"colcon bundle",
+         "cfg":{
+            "workingDir":"./PersonDetection/robot_ws",
+            "cmdArgs":""
+         }
+      },
+      {
+         "id":"PersonDetection_Cfg03",
+         "name":"PersonDetection Simulation",
+         "type":"colcon build",
+         "cfg":{
+            "workingDir":"./PersonDetection/simulation_ws",
+            "cmdArgs":""
+         }
+      },
+      {
+         "id":"PersonDetection_Cfg04",
+         "name":"PersonDetection Simulation",
+         "type":"colcon bundle",
+         "cfg":{
+            "workingDir":"./PersonDetection/simulation_ws",
+            "cmdArgs":""
+         }
+      },
+      {
+         "id":"PersonDetection_SimulationJob1",
+         "name":"PersonDetection Small House",
+         "type":"simulation",
+         "cfg":{
+            "robotApp":{
+               "name":"RoboMakerPersonDetectionRobot",
+               "s3Bucket":"<S3 bucket name for your robot bundle>",
+               "sourceBundleFile":"./PersonDetection/robot_ws/bundle/output.tar.gz",
+               "architecture":"X86_64",
+               "robotSoftwareSuite":{
+                  "version":"Kinetic",
+                  "name":"ROS"
+               },
+               "launchConfig":{
+                  "packageName":"person_detection_robot",
+                  "launchFile":"person_detection.launch"
+               }
+            },
+            "simulationApp":{
+               "name":"RoboMakerPersonDetectionSimulation",
+               "s3Bucket":"<S3 bucket name for your simulation bundle>",
+               "sourceBundleFile":"./PersonDetection/simulation_ws/bundle/output.tar.gz",
+               "architecture":"X86_64",
+               "launchConfig":{
+                  "packageName":"person_detection_simulation",
+                  "launchFile":"small_house_turtlebot_navigation.launch",
+                  "environmentVariables":{
+                     "TURTLEBOT3_MODEL":"waffle_pi"
+                  }
+               },
+               "robotSoftwareSuite":{
+                 "name":"ROS",
+                 "version":"Kinetic"
+               },
+               "simulationSoftwareSuite":{
+                  "name":"Gazebo",
+                  "version":"7"
+               },
+               "renderingEngine":{
+                  "name":"OGRE",
+                  "version":"1.x"
+               }
+            },
+            "simulation":{
+               "outputLocation":"<S3 bucket name for job outputs>",
+               "failureBehavior":"Fail",
+               "maxJobDurationInSeconds":28800,
+               "iamRole":"<IAM role ARN for RoboMaker>"
+            }
+         }
+      },
+      {
+         "id":"PersonDetection_wf1",
+         "type":"workflow",
+         "name":"PersonDetection - Build and Bundle All",
+         "runCfgIds":[
+            "PersonDetection_Cfg01",
+            "PersonDetection_Cfg02",
+            "PersonDetection_Cfg03",
+            "PersonDetection_Cfg04"
+         ]
+      }
+   ]
+}
+

robot_ws/.rosinstall

@@ -0,0 +1,16 @@
+# kinetic.rosinstall
+- setup-file: {local-name: /opt/ros/kinetic/setup.sh}
+
+# Amazon ROS CloudServiceIntegration package dependencies
+- git: {local-name: src/deps/utils-common, uri: 'https://github.com/aws-robotics/utils-common', version: v1.0.0}
+- git: {local-name: src/deps/utils-ros1, uri: 'https://github.com/aws-robotics/utils-ros1', version: v1.0.0}
+- git: {local-name: src/deps/cloudwatch-common, uri: 'https://github.com/aws-robotics/cloudwatch-common', version: v1.0.0}
+- git: {local-name: src/deps/cloudwatchlogs-ros1, uri: 'https://github.com/aws-robotics/cloudwatchlogs-ros1', version: v1.0.0}
+- git: {local-name: src/deps/cloudwatchmetrics-ros1, uri: 'https://github.com/aws-robotics/cloudwatchmetrics-ros1', version: v1.0.0}
+- git: {local-name: src/deps/health-metrics-collector-ros1, uri: 'https://github.com/aws-robotics/health-metrics-collector-ros1', version: v1.0.0}
+- git: {local-name: src/deps/monitoringmessages-ros1, uri: 'https://github.com/aws-robotics/monitoringmessages-ros1', version: v1.0.0}
+- git: {local-name: src/deps/kinesisvideo-common, uri: 'https://github.com/aws-robotics/kinesisvideo-common', version: v1.0.0}
+- git: {local-name: src/deps/kinesisvideo-ros1, uri: 'https://github.com/aws-robotics/kinesisvideo-ros1', version: v1.0.0}
+- git: {local-name: src/deps/kinesisvideo-encoder-common, uri: 'https://github.com/aws-robotics/kinesisvideo-encoder-common', version: v1.0.0}
+- git: {local-name: src/deps/kinesisvideo-encoder-ros1, uri: 'https://github.com/aws-robotics/kinesisvideo-encoder-ros1', version: v1.0.0}
+- git: {local-name: src/deps/tts-ros1, uri: 'https://github.com/aws-robotics/tts-ros1', version: v1.0.0}

robot_ws/src/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2018 Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.