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
  

1. Create a new Amazon ECR Repository:

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

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

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

1. 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= export AWS_SECRET_ACCESS_KEY=

File truncated at 100 lines see the full file

Contributing Guidelines

Thank you for your interest in contributing to our project. Whether it’s a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn’t already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

• A reproducible test case or series of steps
• The version of our code being used
• Any modifications you’ve made relevant to the bug
• Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

1. You are working against the latest source on the main branch.
2. You check existing open, and recently merged, pull requests to make sure someone else hasn’t addressed the problem already.
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

1. Fork the repository.
2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
3. Ensure local tests pass.
4. Commit to your fork using clear commit messages.
5. Send us a pull request, answering any default questions in the pull request interface.
6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional document on forking a repository and creating a pull request.

Finding contributions to work on

Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ‘help wanted’ issues is a great place to start.

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opensource-codeofconduct@amazon.com with any additional questions or comments.

Security issue notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.

Licensing

See the LICENSE file for our project’s licensing. We will ask you to confirm the licensing of your contribution.