aws-samples / greengrass-v2-docker-ros-demo

This sample application demonstrates how to deploy and run ROS applications with IoT Greengrass 2.0 and Docker. The sample application uses local ROS messaging to publish messages between ROS nodes running in different containers, then relays the message over AWS IoT Greengrass 2.0 with MQTT to the cloud.

ROS2 Docker Sample Application with AWS IoT Greengrass 2.0

This sample application demonstrates how to deploy and run ROS applications with IoT Greengrass 2.0 and Docker. The application will run three containers using a docker compose file. Two of the containers, a talker and a listener, will use local ROS messaging to send and receive a “Hello World” message over the ROS topic /chatter. A third container will use the Greengrass SDK to bridge messages published over the ROS topic /chatter with a local socket used by Greengrass for inter-process communication between components. Greengrass will then relay the message over an MQTT topic named chatter in the cloud. Here is an architecture diagram that shows what we will build:

To get started, clone this repository.

git clone https://github.com/aws-samples/greengrass-v2-docker-ros-demo.git ~/greengrass-v2-docker-ros-demo

Prerequsites

Before continuing, make sure your development environment and deployment target (your robot or any Linux-based machine) has the following dependencies

Software and Tools Dependencies

On the development machine (Your laptop or IDE, ex: AWS RoboMaker IDE):

• AWS CLI configured with elevated permissions:

  curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
  unzip awscliv2.zip
  sudo ./aws/install

  Click here for full instructions.

• Docker and Docker Compose:

  • Follow the docker installation steps per these instructions
  • Run these commands to install Docker Compose. For full instructions, click here.

     sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
     sudo chmod +x /usr/local/bin/docker-compose

On the deployment target (the robot):

• Java Runtime Environment:

apt-get update
apt-get install default-jre

• Docker and Docker Compose (same as above).

AWS Resource Dependencies

You will also need the following AWS resources:

• An S3 bucket to stage deployment artifacts .
• A IAM Greengrass Provisioning User with minimal IAM access to provision new robots.
• A base IAM Role to provide robots access to specific AWS resources.

There is a CloudFormation template that will create the above AWS resources here. To launch the stack, run the following command after cloning this respository.

cd ~/greengrass-v2-docker-ros-demo
aws cloudformation create-stack --stack-name GG-Provisioning --template-body file://greengrass/greengrass_bootstrap.template.yaml --capabilities CAPABILITY_NAMED_IAM

Important: If you decide to use the Greengrass Provisioning User created by the cloudformation template above, you will also need to create a set of access credentials (AWS ACCESS KEY ID, and AWS SECRET ACCESS KEY) to use in the provisioning step, per these instructions.

Build Docker Image and Upload to Amazon ECR

Clone this repository and run the build command. It will use the Dockerfile and docker compose YAML file to build the container image.

1. On the development machine:

cd ~/greengrass-v2-docker-ros-demo
DOCKER_BUILDKIT=1 docker-compose build

2. Create a new Amazon ECR Repository:

aws ecr create-repository --repository-name ros-foxy-greengrass-demo | grep repositoryUri

3. The response will look something like this. Copy the URI.

"repositoryUri": "1234567819.dkr.ecr.us-east-1.amazonaws.com/ros-foxy-greengrass-demo",

4. Sign into ECR and upload the new image (replace the ACCOUT_ID and REGION placeholders with your values from the URI above):

aws ecr get-login-password --region <REGION> | docker login --username AWS --password-stdin <ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com

docker tag ros-foxy-greengrass-demo:latest <ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/ ros-foxy-greengrass-demo:latest
docker push <ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/ros-foxy-greengrass-demo:latest

Provision Greengrass 2.0 on the Robot

On the development machine, connect to the robot over SSH or open a shell terminal on the deployment target linux-based device. Run the following commands in the SSH shell (replace the placeholders with your AWS Access Key ID and Secret Key):

Important: First ensure that the robot has Java Runtime Environment (JRE), docker and docker compose installed.

Run the following install and provisioning commands:

export AWS_ACCESS_KEY_ID=<INSERT_YOUR_AWS_ACCESS_KEY_ID_HERE>
export AWS_SECRET_ACCESS_KEY=<INSERT_YOUR_AWS_SECRET_KEY>

curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip > greengrass-nucleus-latest.zip && unzip greengrass-nucleus-latest.zip -d GreengrassCore

sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE -jar ./GreengrassCore/lib/Greengrass.jar \
           --thing-name ROS2_Sample_Robot \
           --thing-group-name ROS2_Sample_Robots \
           --component-default-user ggc_user:ggc_group \
           --provision true \
           --setup-system-service true \
           --deploy-dev-tools true
           
 sudo usermod -aG docker ggc_user

Keep this shell open for later. For more details on AWS IoT Greengrass service invocation, click here.

Create and Deploy the ROS2 Docker Component

Return to the development machine shell.

1. Open the Greengrass recipe file and modify it. Change the placeholders <YOUR_BUCKET_NAME> and <YOUR_PRIVATE_ECR_IMAGE_ID_ROS_GREENGRASS_DEMO> to use an S3 bucket in your account and the ECR URI to the image you created above.

2. Upload the docker compose file to the same Amazon S3 bucket using the object key defined in the recipe:

cd ~/greengrass-v2-docker-ros-demo
aws s3 cp ./docker-compose.yaml s3://<MY_BUCKET_NAME>/com.example.ros2.demo/1.0.0/artifacts/docker-compose.yaml

3. Create the new component with the modified recipe file:

aws greengrassv2 create-component-version \
  --inline-recipe fileb://greengrass/com.example.ros2.demo/1.0.0/recipes/recipe.yaml

4. Open the AWS IoT Greengrass console. Click on Greengrass > Deployments. Click the checkbox beside Deployment for ROS2_Sample_Robots, then press Revise Deployment in the top right of the section.
5. Follow through the deployment wizard. In Step 2, click the checkbox beside com.example.ros2.demo. Click through to the end of the wizard and press Deploy.
6. After a minute or two, run the following commands in the SSH shell on the deployment target (the robot) to see if the ROS containers are running.

cd /greengrass/v2/bin/
sudo ./greengrass-cli component list

Monitor and interact with Greengrass Deployment

1. Use the docker compose file that was deployed to tail the logs and see the pub/sub communication between nodes.

export ARTIFACT_DIR=/greengrass/v2/packages/artifacts/com.example.ros2.demo/1.0.0/
sudo docker-compose -f $ARTIFACT_DIR/docker-compose.yaml logs --follow

2. You should see your application running Hello World messages!

   Optional: To stop and/or restart the ROS containers, run the below commands. To learn more about what you can do with the Greengrass CLI, click here.

   Stop a component:

   sudo /greengrass/v2/bin/greengrass-cli component stop -n com.example.ros2.demo
   

   Check the state (it should be marked as "FINISHED" after a stop operation):

   sudo /greengrass/v2/bin/greengrass-cli component list
   

   Restart a component:

   sudo /greengrass/v2/bin/greengrass-cli component restart -n com.example.ros2.demo
   

3. Open the AWS IoT console and subscribe to the MQTT topic chatter. “Hello World” messages will start to appear in AWS IoT.

Clean-up and Uninstall

1. Follow these instructions to remove Greengrass v2 on the deployment target.
2. Delete the cloudformation stack you created above by following these instructions:
3. Delete the IoT Thing and Thing Group provisioned by Greengrass in the AWS IoT console.

greengrass-v2-docker-ros-demo's Issues

Risk: over-authorization of AWS IoT policy

We are a security research team and we recently discovered that there is an over-authorization security issue with this project's IoT policy.
The affected file is as following:

1. greengrass-v2-docker-ros-demo/greengrass/.policy_1