From b9a5065cbcf61fe52009057f859c152b7f7a2207 Mon Sep 17 00:00:00 2001 From: Nikhil Jha Date: Mon, 16 May 2022 09:47:40 -0700 Subject: [PATCH 01/30] docs: add documentation template --- docs/.gitignore | 5 + docs/404.html | 25 ++ docs/Gemfile | 35 +++ docs/Gemfile.lock | 289 ++++++++++++++++++ docs/_config.yml | 56 ++++ .../2022-05-16-welcome-to-jekyll.markdown | 29 ++ docs/about.markdown | 18 ++ docs/index.markdown | 6 + 8 files changed, 463 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/404.html create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock create mode 100644 docs/_config.yml create mode 100644 docs/_posts/2022-05-16-welcome-to-jekyll.markdown create mode 100644 docs/about.markdown create mode 100644 docs/index.markdown diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..f40fbd8 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +_site +.sass-cache +.jekyll-cache +.jekyll-metadata +vendor diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 0000000..086a5c9 --- /dev/null +++ b/docs/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..129fd9e --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,35 @@ +source "https://rubygems.org" +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +# gem "jekyll", "~> 4.2.2" +# This is the default theme for new Jekyll sites. You may change this to anything you like. +gem "minima", "~> 2.5" +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +gem "github-pages", group: :jekyll_plugins +# If you have any plugins, put them here! +group :jekyll_plugins do + gem "jekyll-feed", "~> 0.12" +end + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", "~> 1.2" + gem "tzinfo-data" +end + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin] + +# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem +# do not have a Java counterpart. +gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby] + +gem "webrick", "~> 1.7" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..d6844be --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,289 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (6.0.5) + concurrent-ruby (~> 1.0, >= 1.0.2) + i18n (>= 0.7, < 2) + minitest (~> 5.1) + tzinfo (~> 1.1) + zeitwerk (~> 2.2, >= 2.2.2) + addressable (2.8.0) + public_suffix (>= 2.0.2, < 5.0) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.23.4) + concurrent-ruby (1.1.10) + dnsruby (1.61.9) + simpleidn (~> 0.1) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.15.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + execjs (2.8.1) + faraday (1.10.0) + faraday-em_http (~> 1.0) + faraday-em_synchrony (~> 1.0) + faraday-excon (~> 1.1) + faraday-httpclient (~> 1.0) + faraday-multipart (~> 1.0) + faraday-net_http (~> 1.0) + faraday-net_http_persistent (~> 1.0) + faraday-patron (~> 1.0) + faraday-rack (~> 1.0) + faraday-retry (~> 1.0) + ruby2_keywords (>= 0.0.4) + faraday-em_http (1.0.0) + faraday-em_synchrony (1.0.0) + faraday-excon (1.1.0) + faraday-httpclient (1.0.1) + faraday-multipart (1.0.3) + multipart-post (>= 1.2, < 3) + faraday-net_http (1.0.1) + faraday-net_http_persistent (1.2.0) + faraday-patron (1.0.0) + faraday-rack (1.0.0) + faraday-retry (1.0.3) + ffi (1.15.5) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (226) + github-pages-health-check (= 1.17.9) + jekyll (= 3.9.2) + jekyll-avatar (= 0.7.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.2.0) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.15.1) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.13.0) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.12.0) + kramdown (= 2.3.2) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.3) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.13.4, < 2.0) + rouge (= 3.26.0) + terminal-table (~> 1.4) + github-pages-health-check (1.17.9) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (>= 3.0, < 5.0) + typhoeus (~> 1.3) + html-pipeline (2.14.1) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.8.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.9.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.7.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.2.0) + commonmarker (~> 0.23.4) + jekyll (~> 3.9.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 4.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.15.1) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.13.0) + jekyll (>= 3.4, < 5.0) + octokit (~> 4.0, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.12.0) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + kramdown (2.3.2) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.3) + listen (3.7.1) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.3.6) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.15.0) + multipart-post (2.1.1) + nokogiri (1.13.6-arm64-darwin) + racc (~> 1.4) + octokit (4.22.0) + faraday (>= 0.9) + sawyer (~> 0.8.0, >= 0.5.3) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (4.0.7) + racc (1.6.0) + rb-fsevent (0.11.1) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.5) + rouge (3.26.0) + ruby2_keywords (0.0.5) + rubyzip (2.3.2) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.8.2) + addressable (>= 2.3.5) + faraday (> 0.8, < 2.0) + simpleidn (0.2.1) + unf (~> 0.1.4) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.4.0) + ethon (>= 0.9.0) + tzinfo (1.2.9) + thread_safe (~> 0.1) + unf (0.1.4) + unf_ext + unf_ext (0.0.8.1) + unicode-display_width (1.8.0) + webrick (1.7.0) + zeitwerk (2.5.4) + +PLATFORMS + arm64-darwin-21 + +DEPENDENCIES + github-pages + http_parser.rb (~> 0.6.0) + jekyll-feed (~> 0.12) + minima (~> 2.5) + tzinfo (~> 1.2) + tzinfo-data + wdm (~> 0.1.1) + webrick (~> 1.7) + +BUNDLED WITH + 2.3.13 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..8df345c --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,56 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. +# +# If you need help with YAML syntax, here are some quick references for you: +# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml +# https://learnxinyminutes.com/docs/yaml/ +# +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. + +title: Your awesome title +email: your-email@example.com +description: >- # this means to ignore newlines until "baseurl:" + Write an awesome description for your new site here. You can edit this + line in _config.yml. It will appear in your document head meta (for + Google search results) and in your feed.xml site description. +baseurl: "" # the subpath of your site, e.g. /blog +url: "" # the base hostname & protocol for your site, e.g. http://example.com +twitter_username: jekyllrb +github_username: jekyll + +# Build settings +# theme: minima +remote_theme: just-the-docs/just-the-docs +plugins: + - jekyll-feed + +# Exclude from processing. +# The following items will not be processed, by default. +# Any item listed under the `exclude:` key here will be automatically added to +# the internal "default list". +# +# Excluded items can be processed by explicitly listing the directories or +# their entries' file path in the `include:` list. +# +# exclude: +# - .sass-cache/ +# - .jekyll-cache/ +# - gemfiles/ +# - Gemfile +# - Gemfile.lock +# - node_modules/ +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/docs/_posts/2022-05-16-welcome-to-jekyll.markdown b/docs/_posts/2022-05-16-welcome-to-jekyll.markdown new file mode 100644 index 0000000..acc3671 --- /dev/null +++ b/docs/_posts/2022-05-16-welcome-to-jekyll.markdown @@ -0,0 +1,29 @@ +--- +layout: post +title: "Welcome to Jekyll!" +date: 2022-05-16 09:44:24 -0700 +categories: jekyll update +--- +You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated. + +Jekyll requires blog post files to be named according to the following format: + +`YEAR-MONTH-DAY-title.MARKUP` + +Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. After that, include the necessary front matter. Take a look at the source for this post to get an idea about how it works. + +Jekyll also offers powerful support for code snippets: + +{% highlight ruby %} +def print_hi(name) + puts "Hi, #{name}" +end +print_hi('Tom') +#=> prints 'Hi, Tom' to STDOUT. +{% endhighlight %} + +Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk]. + +[jekyll-docs]: https://jekyllrb.com/docs/home +[jekyll-gh]: https://github.com/jekyll/jekyll +[jekyll-talk]: https://talk.jekyllrb.com/ diff --git a/docs/about.markdown b/docs/about.markdown new file mode 100644 index 0000000..8b4e0b2 --- /dev/null +++ b/docs/about.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: About +permalink: /about/ +--- + +This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/) + +You can find the source code for Minima at GitHub: +[jekyll][jekyll-organization] / +[minima](https://github.com/jekyll/minima) + +You can find the source code for Jekyll at GitHub: +[jekyll][jekyll-organization] / +[jekyll](https://github.com/jekyll/jekyll) + + +[jekyll-organization]: https://github.com/jekyll diff --git a/docs/index.markdown b/docs/index.markdown new file mode 100644 index 0000000..0671507 --- /dev/null +++ b/docs/index.markdown @@ -0,0 +1,6 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: home +--- From e0c459b419bf51dd1615be15aa83d18e1d4ebed2 Mon Sep 17 00:00:00 2001 From: Nikhil Jha Date: Mon, 16 May 2022 11:43:45 -0700 Subject: [PATCH 02/30] doc: add description to docs website --- docs/_config.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 8df345c..4113f0c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -18,16 +18,16 @@ # You can create any custom variable you would like, and they will be accessible # in the templates via {{ site.myvariable }}. -title: Your awesome title -email: your-email@example.com +title: FogROS2 Documentation +email: autolab@berkeley.edu description: >- # this means to ignore newlines until "baseurl:" - Write an awesome description for your new site here. You can edit this - line in _config.yml. It will appear in your document head meta (for - Google search results) and in your feed.xml site description. + FogROS2 extends ROS 2 for the cloud deployment of computational graphs in a + security-conscious manner. It allows researchers to easily deploy ROS abstractions + across cloud providers with minimal effort. baseurl: "" # the subpath of your site, e.g. /blog url: "" # the base hostname & protocol for your site, e.g. http://example.com -twitter_username: jekyllrb -github_username: jekyll +twitter_username: AUTOLab_Cal +github_username: BerkeleyAutomation # Build settings # theme: minima From 7b373726f140058d2bd6b7e901634e5847638353 Mon Sep 17 00:00:00 2001 From: Nikhil Jha Date: Mon, 16 May 2022 11:51:02 -0700 Subject: [PATCH 03/30] chore: mdlint --- README.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index cca1b3f..a192fc8 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ [`FogROS2`](https://github.com/BerkeleyAutomation/FogROS2) extends ROS 2 for cloud deployment of computational graphs in a security-conscious manner. It allows researchers to easily and securely deploy ROS abstractions across cloud providers with minimal effort, thus gaining access to additional computing substrates including CPU cores, GPUs, FPGAs, or TPUs, as well as pre-deployed software made available by other researchers. To do so, `FogROS2` extends the ROS 2 launch system, introducing additional syntax to allow roboticists to specify at launch time which components of their architecture will be deployed to the cloud and which components will be deployed on the edge. - - [FogROS2](#fogros2) - [Install](#install) - [Quickstart](#quickstart) @@ -16,13 +15,18 @@ - [Setting Up Automatic Image Transport](#setting-up-automatic-image-transport) - [Command Line Interface](#command-line-interface) - [Some Common Issues](#some-common-issues) - - [Running Examples:](#running-examples) + - [Running Examples](#running-examples) ## Install + ### Quickstart + If you are new to ROS and Ubuntu, and want to install FogROS 2 (and ROS 2) and its requisites from scratch, follow instructions [here](https://github.com/BerkeleyAutomation/FogROS2/blob/humble/QUICKSTART.md). + ### Docker (Recommended) + Alternatively, you can simplify reproduction using an OS virtualization environment with Docker: + ```bash git clone -b humble https://github.com/BerkeleyAutomation/FogROS2 cd FogROS2 @@ -36,22 +40,26 @@ aws configure #Build Docker Image docker build -t fogros2 . ``` + By default, this command will build a docker image for ROS Rolling and Ubuntu 22.04 (jammy). These defaults can be changed using the `--build-arg` flag (e.g., `docker build -t fogros2:focal-humble . --build-arg UBUNTU_DISTRO=focal --build-arg ROS_DISTRO=humble` will build a ROS Humble image with Ubuntu 20.04 (focal)). *Note: the Dockerfile is cooked for x86_64. If you're using a workstation with an Arm-based architecture (e.g. an M1), build the container with the `docker build --platform linux/amd64 -t fogros2 .`*. ### Natively + `FogROS2` is actually a ROS meta-package, so you can just fetch it in your workspace, build it, source the workspace as an overlay and start using its capabilities. #### Install Dependencies ROS 2 dependencies: -``` + +```bash # If using Ubuntu 22.04 sudo apt install ros-rolling-rmw-cyclonedds-cpp ``` FogROS 2 dependencies: -``` + +```bash sudo apt install python3-pip wireguard unzip sudo pip3 install wgconfig boto3 paramiko scp @@ -72,7 +80,6 @@ colcon build # re-build the workspace source install/setup.bash ``` - ## Launch ROS 2 computational graphs in the cloud ### Docker (Recommended) @@ -88,7 +95,9 @@ ros2 launch fogros2_examples talker.aws.launch.py (*Note: the Dockerfile is cooked for x86_64. If you're using a workstation with an Arm-based architecture (e.g. an M1), run the container with the `docker run -it --platform linux/amd64 --rm --net=host --cap-add=NET_ADMIN fogros2`*.) ### Native + Note: These commands must be run from the root of your ROS workspace. + ```bash source /opt/ros//setup.bash source install/setup.bash @@ -99,11 +108,13 @@ ros2 launch fogros2_examples talker.aws.launch.py ``` ## Run your own robotics applications + If using, for example, Docker take the following steps: Step 1: Mount your robotics application to docker's folder. For example, -``` + +```bash docker run -it --rm \ --net=host --cap-add=NET_ADMIN \ .... @@ -111,13 +122,13 @@ docker run -it --rm \ ... keplerc/ros2:latest /bin/bash ``` -You may also `git clone` your development repo to the docker container instead. +You may also `git clone` your development repo to the docker container instead. Step 2: Write the FogROS2 launch file. Examples of launch files can be found in the talker*.launch.py [here](https://github.com/BerkeleyAutomation/FogROS2/tree/humble/fogros2_examples/launch). - ## Setting Up Automatic Image Transport + Step 1: Identify all topics that need to use a compressed transport. Step 2: In a `fogros2.CloudNode`, add the parameter `stream_topics=[]`, where `stream_topics` is a list of tuples @@ -138,6 +149,7 @@ Adding the above argument to a `fogros2.CloudNode` makes the topic `/camera/imag Please note that all cloud nodes that are expecting raw images will be remapped to `TOPIC_NAME/cloud` to remove any topic naming conflicts. (TODO: Automate remapping) ## Command Line Interface + We currently support the following CLI commands for easier debugging and development. ```bash @@ -155,9 +167,11 @@ ros2 fog delete all ``` ## Some Common Issues -1. Warning: _2 packages has stderr outputs: fogros2 fogros2_examples_ after running colcon build. This warning occurs in Ubuntu 22.04 (jammy) builds, but does not affect functionality. See https://github.com/BerkeleyAutomation/FogROS2/issues/45. Your installation should still work. -2. _[WARN] [1652044293.921367226] [fogros2.scp]: [Errno None] Unable to connect to port 22 on xx.xx.xx.xxx, retrying..._ . This warning occurs when AWS has not yet started the instance. This message should eventually be replaced by _SCP Connected!_ once the instance is started. -3. _WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behavior with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv_. This warning is often seen when installing packages on the cloud instance, but can be ignored. -## Running Examples: +1. Warning: *2 packages has stderr outputs: fogros2 fogros2_examples* after running colcon build. This warning occurs in Ubuntu 22.04 (jammy) builds, but does not affect functionality. See . Your installation should still work. +2. *[WARN] [1652044293.921367226] [fogros2.scp]: [Errno None] Unable to connect to port 22 on xx.xx.xx.xxx, retrying...* . This warning occurs when AWS has not yet started the instance. This message should eventually be replaced by *SCP Connected!* once the instance is started. +3. *WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behavior with the system package manager. It is recommended to use a virtual environment instead: *. This warning is often seen when installing packages on the cloud instance, but can be ignored. + +## Running Examples + We have used FogROS for 3 example use-cases (motion planning, grasp planning, and SLAM map building). Please see our [examples repo](https://github.com/BerkeleyAutomation/fogros2-examples) for these and how to run them. From b0cc5598c1a7805dc2b03077b677b37f09f0749e Mon Sep 17 00:00:00 2001 From: Nikhil Jha Date: Mon, 16 May 2022 11:57:27 -0700 Subject: [PATCH 04/30] doc: remove forced base url --- docs/_config.yml | 2 -- .../2022-05-16-welcome-to-jekyll.markdown | 29 ------------------- 2 files changed, 31 deletions(-) delete mode 100644 docs/_posts/2022-05-16-welcome-to-jekyll.markdown diff --git a/docs/_config.yml b/docs/_config.yml index 4113f0c..ff18d6e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -24,8 +24,6 @@ description: >- # this means to ignore newlines until "baseurl:" FogROS2 extends ROS 2 for the cloud deployment of computational graphs in a security-conscious manner. It allows researchers to easily deploy ROS abstractions across cloud providers with minimal effort. -baseurl: "" # the subpath of your site, e.g. /blog -url: "" # the base hostname & protocol for your site, e.g. http://example.com twitter_username: AUTOLab_Cal github_username: BerkeleyAutomation diff --git a/docs/_posts/2022-05-16-welcome-to-jekyll.markdown b/docs/_posts/2022-05-16-welcome-to-jekyll.markdown deleted file mode 100644 index acc3671..0000000 --- a/docs/_posts/2022-05-16-welcome-to-jekyll.markdown +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: post -title: "Welcome to Jekyll!" -date: 2022-05-16 09:44:24 -0700 -categories: jekyll update ---- -You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated. - -Jekyll requires blog post files to be named according to the following format: - -`YEAR-MONTH-DAY-title.MARKUP` - -Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. After that, include the necessary front matter. Take a look at the source for this post to get an idea about how it works. - -Jekyll also offers powerful support for code snippets: - -{% highlight ruby %} -def print_hi(name) - puts "Hi, #{name}" -end -print_hi('Tom') -#=> prints 'Hi, Tom' to STDOUT. -{% endhighlight %} - -Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk]. - -[jekyll-docs]: https://jekyllrb.com/docs/home -[jekyll-gh]: https://github.com/jekyll/jekyll -[jekyll-talk]: https://talk.jekyllrb.com/ From 728a607d55e8512ce6b2a5950b48b5333f3ac0da Mon Sep 17 00:00:00 2001 From: Nikhil Jha Date: Mon, 16 May 2022 15:07:22 -0700 Subject: [PATCH 05/30] doc: fix line wrap --- docs/_config.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index ff18d6e..4341b51 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -18,7 +18,7 @@ # You can create any custom variable you would like, and they will be accessible # in the templates via {{ site.myvariable }}. -title: FogROS2 Documentation +title: FogROS2 Docs email: autolab@berkeley.edu description: >- # this means to ignore newlines until "baseurl:" FogROS2 extends ROS 2 for the cloud deployment of computational graphs in a @@ -28,7 +28,6 @@ twitter_username: AUTOLab_Cal github_username: BerkeleyAutomation # Build settings -# theme: minima remote_theme: just-the-docs/just-the-docs plugins: - jekyll-feed @@ -52,3 +51,10 @@ plugins: # - vendor/cache/ # - vendor/gems/ # - vendor/ruby/ + +# Aux links for the upper right navigation +aux_links: + "GitHub": + - "https://github.com/BerkeleyAutomation/FogROS2" + +ga_tracking: G-5Z6QQZHE0Z From aa83c14e65fa7815fd7f53cda9dd4ca22bdb6ff2 Mon Sep 17 00:00:00 2001 From: Jeff Ichnowski Date: Tue, 17 May 2022 18:44:15 -0400 Subject: [PATCH 06/30] Rename about.markdown to about.md --- docs/{about.markdown => about.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{about.markdown => about.md} (100%) diff --git a/docs/about.markdown b/docs/about.md similarity index 100% rename from docs/about.markdown rename to docs/about.md From 0166895018eec223919e2cd08a650e323100c717 Mon Sep 17 00:00:00 2001 From: Jeff Ichnowski Date: Tue, 17 May 2022 18:47:54 -0400 Subject: [PATCH 07/30] Update about.md --- docs/about.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/docs/about.md b/docs/about.md index 8b4e0b2..d93eab8 100644 --- a/docs/about.md +++ b/docs/about.md @@ -4,15 +4,6 @@ title: About permalink: /about/ --- -This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/) +FogROS 2 is an open-source cloud-robotics pilot platform from UC Berkeley. Cloud computing using commercial clusters such as Amazon Web Services (AWS) is now fast enough to enable secure compute-intensive robot functions such as SLAM map building from video, grasp planning, and high dimensional motion planning to be performed in the Cloud using high-performance hardware and GPUs in near real-time. FogROS 2 offers ROS 2 functions to streamline the deployment of robot code. Developers do not need to change their code–they need only to specify an AWS configuration of computers that they want their code to run. FogROS 2 coordinates the details of initiating hardware instances, installing software and dependencies, securing robot-cloud communication, and launching cloud processes. -You can find the source code for Minima at GitHub: -[jekyll][jekyll-organization] / -[minima](https://github.com/jekyll/minima) - -You can find the source code for Jekyll at GitHub: -[jekyll][jekyll-organization] / -[jekyll](https://github.com/jekyll/jekyll) - - -[jekyll-organization]: https://github.com/jekyll +In example applications, we used FogROS 2 to deploy compute-intensive ROS 2 nodes for SLAM, Grasp Planning, and Motion Planning to the cloud. For Visual SLAM, we ran an [ORB-SLAM 2](https://github.com/raulmur/ORB_SLAM2) Node on a multi-core cloud computer and we got a 2x speedup. For Grasp Planning, we ran the [Dex-Net](https://github.com/BerkeleyAutomation/dex-net) Node on a GPU instance in the cloud and got a 12x speedup. For Motion Planning, we ran [Motion Planning Templates](https://robotics.cs.unc.edu/mpt/) on a 96-core cloud computer and got a 28x speedup. From 9c77eaed3f482fde8dd7d76ec3aeaaaea78a345f Mon Sep 17 00:00:00 2001 From: Jeff Ichnowski Date: Tue, 17 May 2022 18:52:35 -0400 Subject: [PATCH 08/30] Added example apps --- docs/fogros2_dexnet_example.svg | 277 ++++++++ docs/fogros2_mpt_example.svg | 1077 +++++++++++++++++++++++++++++ docs/fogros2_orbslam2_example.svg | 368 ++++++++++ 3 files changed, 1722 insertions(+) create mode 100644 docs/fogros2_dexnet_example.svg create mode 100644 docs/fogros2_mpt_example.svg create mode 100644 docs/fogros2_orbslam2_example.svg diff --git a/docs/fogros2_dexnet_example.svg b/docs/fogros2_dexnet_example.svg new file mode 100644 index 0000000..8038fe2 --- /dev/null +++ b/docs/fogros2_dexnet_example.svg @@ -0,0 +1,277 @@ + + + +1RobotCameraNodeGraspingNodeInstanceGQCNNDockerNodeCameraTopich.264GraspTopicGPU diff --git a/docs/fogros2_mpt_example.svg b/docs/fogros2_mpt_example.svg new file mode 100644 index 0000000..8be363f --- /dev/null +++ b/docs/fogros2_mpt_example.svg @@ -0,0 +1,1077 @@ + + + +1RobotSensorNodeTaskNodeFollowMotionNodeInstanceMotionPlannerNodeObstacleTopicStart/GoalTopicMotionPlanTopicCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPUCPU diff --git a/docs/fogros2_orbslam2_example.svg b/docs/fogros2_orbslam2_example.svg new file mode 100644 index 0000000..f9abd9c --- /dev/null +++ b/docs/fogros2_orbslam2_example.svg @@ -0,0 +1,368 @@ + + + +1RobotCameraNodeBrowserInstanceSLAMNodeCameraTopich.264SLAMTopicCPUCPUCPUCPUCPUCPU From e1ea6e1b0f8b6d6190b1e59bec28770e9607bb54 Mon Sep 17 00:00:00 2001 From: Jeff Ichnowski Date: Tue, 17 May 2022 18:55:30 -0400 Subject: [PATCH 09/30] Added links to example images. --- docs/about.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/about.md b/docs/about.md index d93eab8..408ce03 100644 --- a/docs/about.md +++ b/docs/about.md @@ -7,3 +7,7 @@ permalink: /about/ FogROS 2 is an open-source cloud-robotics pilot platform from UC Berkeley. Cloud computing using commercial clusters such as Amazon Web Services (AWS) is now fast enough to enable secure compute-intensive robot functions such as SLAM map building from video, grasp planning, and high dimensional motion planning to be performed in the Cloud using high-performance hardware and GPUs in near real-time. FogROS 2 offers ROS 2 functions to streamline the deployment of robot code. Developers do not need to change their code–they need only to specify an AWS configuration of computers that they want their code to run. FogROS 2 coordinates the details of initiating hardware instances, installing software and dependencies, securing robot-cloud communication, and launching cloud processes. In example applications, we used FogROS 2 to deploy compute-intensive ROS 2 nodes for SLAM, Grasp Planning, and Motion Planning to the cloud. For Visual SLAM, we ran an [ORB-SLAM 2](https://github.com/raulmur/ORB_SLAM2) Node on a multi-core cloud computer and we got a 2x speedup. For Grasp Planning, we ran the [Dex-Net](https://github.com/BerkeleyAutomation/dex-net) Node on a GPU instance in the cloud and got a 12x speedup. For Motion Planning, we ran [Motion Planning Templates](https://robotics.cs.unc.edu/mpt/) on a 96-core cloud computer and got a 28x speedup. + +![ORB-SLAM2](fogros2_orbslam2_example.svg) +![Dex-Net](fogros2_dexnet_example.svg) +![Motion Planning Templates](fogros2_mpt_example.svg) From f1587c283a7b05850724a2aa36f3fdf861cbf201 Mon Sep 17 00:00:00 2001 From: Jeff Ichnowski Date: Tue, 17 May 2022 22:57:20 -0400 Subject: [PATCH 10/30] Create cloud_robotics.md --- docs/cloud_robotics.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/cloud_robotics.md diff --git a/docs/cloud_robotics.md b/docs/cloud_robotics.md new file mode 100644 index 0000000..34d8dcc --- /dev/null +++ b/docs/cloud_robotics.md @@ -0,0 +1,37 @@ +Cloud Robotics +=== +Cloud robotics encompasses many relations between the cloud and Robotics. Here we focus on what the cloud offers, explicitly focusing on the capabilities FogROS 2 can give robots by using the cloud. + +What is the cloud? +--- +The cloud, in short, offers pay-per-use networked access to computing resources. Cloud service providers, such as Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure, set up and maintain computing hardware, such as multi-core servers, graphics processing units (GPUs), tensor processing units (TPUs), field-programmable gate arrays (FPGAs), and more. To use the computing hardware, one signs up for the service using a credit card, then uses either a browser-based or program-based interface to turn on and off, configure, and access these computers. + +Cloud service providers house their computers in different _data centers_ in different _regions_ around the world. The reason for this will be explained next. + +Cloud computing latency +--- +Latency of computation is often critical in robot applications. Whether computing a new path, reconstructing an environment, or planning a manipulation, it is desirable to do it fast. Robots may find that computations are too slow when using their onboard computing capabilities alone. Using high-end or hardware-accelerated computing in the cloud can speed up the computation but at the cost of the network round-trip time between robot and cloud. Using the cloud thus only gains an advantage over robot-only computation when the combined cloud computing time and the network round-trip time is faster than robot-only. + +For example, robots often do not have onboard GPUs, but many modern robot algorithms benefit significantly from GPU processing. When a forward pass on a deep neural network takes 14 seconds on a robot's CPU and requires only 0.6 seconds on a GPU, the potential speedup using the cloud is significant. + +Network latency to the cloud +--- +The network latency to the cloud can be surprisingly short. The most crucial factor is the distance between the robot and the cloud. The farther away, the longer the latency (this is due to the speed of light). A secondary factor is the bandwidth or bitrate of the network connection between the robot and the cloud. + +To understand bandwidth or bitrate, try out an internet speed test tool. + +To understand the latency to the cloud, try out [cloudping.info]. This tool sends a small packet to the different data centers and measures the time before the response comes back. You can expect response times in the 10 to 40 ms range for nearby data centers. + +With [cloudping.info], you can quickly understand which data center you should use for you cloud robotics applications. + +What is the edge? +--- +The edge refers to computing resources as close as possible to the robot. As latency is often a critical factor in many applications, having computers closer to the robot is often desirable. + +What is the fog? +--- +The fog encompasses everything between and including the cloud and the edge computing resources. + +FogROS 2 and Cloud Robotics +--- +FogROS 2 integrates ROS 2 applications with the cloud by streamlining the process of running ROS 2 nodes in the cloud and having them communicate with the robot. FogROS 2 takes care of: setting up cloud computers, installing ROS and dependencies, securing network communications, starting remote nodes, and more. As a user, you will need only to configure which nodes get deployed to which region and computer type. From f11c5c0406a4dc72f55a6434a3a0b29cd1b965d9 Mon Sep 17 00:00:00 2001 From: Jeff Ichnowski Date: Tue, 17 May 2022 23:42:08 -0400 Subject: [PATCH 11/30] Create getting_started.md --- docs/getting_started.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/getting_started.md diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..e3139fb --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,25 @@ +Getting Started +=== +FogROS 2 streamlines the process of running parts of a ROS 2 application in the cloud. The main benefit is to speed up compute-intensive nodes by using cloud-based high-end computers and hardware acceleration. The only change typically needed is the launch configuration. + +Before describing how to configure a ROS 2 application to use FogROS 2, we will discuss two critical things: _region_ and _instance type_. + +Region +--- +The region is where the cloud computer is physically located. Since network latency increases as the distance between robot and cloud increases, selecting a physically close region is essential. A great tool to understand regions and latency is [cloudping.info]. Usually, it is best to select the region with the lowest latency (we will discuss in a moment). + +Instance Type +--- +Cloud computers have different hardware specifications with a range of options: the number of CPU cores, amount of memory, types of included hardware accelerators (e.g., GPU, TPU, FPGA), and more. Here are a few example considerations: + +Does the ROS node use a deep neural network and NOT have a GPU or TPU? If so, a cloud computer with a GPU or TPU could speed up computation significantly. +Does the ROS node make use of multi-core concurrency? If so, a cloud computer with many more cores than the robot has (e.g., 32-cores, 72-cores, 96-cores) could speed up computation significantly. +Could the ROS node use a specialized hardware accelerator such as an FPGA? If so, a cloud computer with the appropriate hardware could speed up computation significantly. +Are there more nodes running than the robot can handle? If so, hardware acceleration is less important than just getting enough computer cores to meet the demand. + +The second part of instance type selection is determining the instance size, or how much computing is enough to best price/performance ratio (or to just fit into a budge). Higher-end instance types cost more money per hour, so ideally, one should select the minimum specification to meet performance criteria. For example, if the application gains no benefit beyond a 32-core computer, selecting a 92-core computer would waste money. How to best determine the instance size can come from a deep understanding of the application code or running a series of experiments with different instance sizes. + +Instance types and Regions +--- +The one caveat in the above discussion is that not all regions have all instance types. You may have to look at different regions or instance types to find the best computing resource for your application. + From 7f26eec7e65e435aa11cff568aa518b58d12c7b0 Mon Sep 17 00:00:00 2001 From: Mike Danielczuk Date: Tue, 17 May 2022 21:49:46 -0700 Subject: [PATCH 12/30] add cli docs --- docs/cli.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 docs/cli.md diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..bcd534f --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,153 @@ +--- +layout: page +title: CLI +permalink: /cli/ +--- + +# Command Line Interface (CLI) +FogROS2 uses Python entry points to extend the commands and verbs for ROS 2's CLI. Specifically, the `fogros2` package adds the `fog` command with three verbs, `list`, `connect` and `delete` for easy viewing of, interaction with, and termination of remote instances, respectively. More information about commands or verbs can be found by running `ros2 fog --help` or `ros2 fog --help`. + +
+ + CLI Commands + + {: .text-delta } + 1. TOC +{:toc} +
+ +## list +Prints information about existing FogROS2 instances. + +### Usage +**ros2 fog list** *[-h] [\-\-region REGION [REGION ...]]* + +### Description +Prints a list of details -- instance name, cloud service provider (currently always AWS), region, instance type, region, id, IP address, SSH key, disk size, AMI, and state -- for existing FogROS2 instances. With no *REGION* specified, this command defaults to listing instances in the region set in the user's AWS configuration or in the corresponding environment variable. Otherwise, it lists all FogROS2 instances in *REGION* or in multiple regions if specified. + +### Options +**\-h, \-\-help** +Print usage, argument, and options information and exit. + +**\-\-region** *REGION [REGION ...]* +Specify the AWS region(s) for listing instances (overrides config or environment variables that are set). Multiple regions can be listed and separated by a space, and the output will include instances from all regions listed. + +### Examples +If there are two current instances running with names "great-bulkhead" and "associative-singularity": +```bash +$ ros2 fog list +====== great-bulkhead ====== +cloud_service_provider: AWS +ec2_region: None +ec2_instance_type: t2.micro +ec2_instance_id: i-002391eea4a22a6ba +public_ip: 13.57.237.42 +ssh_key: FogROS2KEY-great-bulkhead +disk_size: 30 +aws_ami_image: ami-00f25057ddc9b310b +state: running +====== associative-singularity ====== +cloud_service_provider: AWS +ec2_region: None +ec2_instance_type: t2.micro +ec2_instance_id: i-071770e8a9f6d18e9 +public_ip: 18.144.35.60 +ssh_key: FogROS2KEY-associative-singularity +disk_size: 30 +aws_ami_image: ami-00f25057ddc9b310b +state: running +``` + +One could also receive the same output as above by specifying the region directly: +```bash +$ ros2 fog list --region us-west-1 +``` + +## connect +Opens a shell connection to an existing instance. + +### Usage +**ros2 fog connect** *[\-h] [\-\-region [REGION [REGION ...]]] [\-\-user [USER]] NAME* + +### Description +Connects via SSH to an existing FogROS2 instance with name *NAME*, allowing the user to run commands from a shell directly on the instance. FogROS2 instance names can be found using the `list` command. If no instances with name *NAME* are found in the specified region, this command will print "No matching instance found" and exit. + +### Options +**\-h, \-\-help** +Print usage, argument, and options information and exit. + +**\-\-region** *REGION [REGION ...]* +Match only instances with name *NAME* in the AWS region(s) *REGION* (overrides config or environment variables that are set). Multiple regions can be listed and separated by a space, and all regions will be searched for an instance with name *NAME*. + +**\-u** *USER*, **\-\-user** *USER* +Connect as user *USER* to the remote SSH instance. If this option is not specified, the default user is "ubuntu". + +### Examples +To connect to a currently running instance called "great-bulkhead": +```bash +$ ros2 fog connect great-bulkhead +Welcome to Ubuntu 20.04.3 LTS (GNU/Linux 5.11.0-1022-aws x86_64) + + * Documentation: https://help.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/advantage + + System information disabled due to load higher than 1.0 + + +231 updates can be applied immediately. +163 of these updates are standard security updates. +To see these additional updates run: apt list --upgradable + + +Last login: Thu Feb 24 19:38:54 2022 from 128.32.37.69 +ubuntu@ip-172-31-7-52:~$ +``` + +*Note: Output is given as an example, but likely will be different from above.* +*Note: A notice saying that the authenticity of the host can't be established may be shown; you will need to confirm that you wish to continue to connect in this case.* + +## delete +Terminates a running instance. + +### Usage +**ros2 fog delete** *[\-h] [\-\-region [REGION [REGION ...]]] [\-\-dry-run] NAME* + +### Description +Terminates an existing FogROS2 instance with name *NAME* and removes the key pair and data folder associated with the instance. If *NAME* is `all`, then all FogROS2 instances in the specified regions will be terminated. FogROS2 instance names can be found using the `list` command. If no instances with name *NAME* are found in the specified region, this command will print "No EC2 instances found with the specified name; check list to be sure name is correct! +No instances deleted" and exit. + +### Options +**\-\-dry-run** +Show which instances and keys would be terminated and deleted without actually executing the commands to do so. + +**\-h, \-\-help** +Print usage, argument, and options information and exit. + +**\-\-region** *REGION [REGION ...]* +Match only instances with name *NAME* in the AWS region(s) *REGION* (overrides config or environment variables that are set). Multiple regions can be listed and separated by a space, and all regions will be searched for an instance with name *NAME*. + +### Examples +The following examples assume there are two instances running with names "great-bulkhead" and "associative-singularity". + +To terminate both running instances: +```bash +$ ros2 fog delete all +Deleting great-bulkhead i-002391eea4a22a6ba + terminating instance i-002391eea4a22a6ba + deleting key pair FogROS2KEY-great-bulkhead + done. +Deleting associative-singularity i-071770e8a9f6d18e9 + terminating instance i-071770e8a9f6d18e9 + deleting key pair FogROS2KEY-associative-singularity + done. +``` + +To terminate just "great-bulkhead": +```bash +$ ros2 fog delete great-bulkhead +Deleting great-bulkhead i-002391eea4a22a6ba + terminating instance i-002391eea4a22a6ba + deleting key pair FogROS2KEY-great-bulkhead + done. +``` \ No newline at end of file From 359c29cafe95a89658fdbf5a0e6d670bd97a5b58 Mon Sep 17 00:00:00 2001 From: Mike Danielczuk Date: Tue, 17 May 2022 22:08:04 -0700 Subject: [PATCH 13/30] nav order, fix some links and typos --- docs/about.md | 5 +++-- docs/cli.md | 18 ++++++++++-------- docs/cloud_robotics.md | 15 +++++++++++---- docs/getting_started.md | 19 +++++++++++++------ 4 files changed, 37 insertions(+), 20 deletions(-) diff --git a/docs/about.md b/docs/about.md index 408ce03..c028e62 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,12 +1,13 @@ --- layout: page title: About -permalink: /about/ +permalink: /about +nav_order: 0 --- FogROS 2 is an open-source cloud-robotics pilot platform from UC Berkeley. Cloud computing using commercial clusters such as Amazon Web Services (AWS) is now fast enough to enable secure compute-intensive robot functions such as SLAM map building from video, grasp planning, and high dimensional motion planning to be performed in the Cloud using high-performance hardware and GPUs in near real-time. FogROS 2 offers ROS 2 functions to streamline the deployment of robot code. Developers do not need to change their code–they need only to specify an AWS configuration of computers that they want their code to run. FogROS 2 coordinates the details of initiating hardware instances, installing software and dependencies, securing robot-cloud communication, and launching cloud processes. -In example applications, we used FogROS 2 to deploy compute-intensive ROS 2 nodes for SLAM, Grasp Planning, and Motion Planning to the cloud. For Visual SLAM, we ran an [ORB-SLAM 2](https://github.com/raulmur/ORB_SLAM2) Node on a multi-core cloud computer and we got a 2x speedup. For Grasp Planning, we ran the [Dex-Net](https://github.com/BerkeleyAutomation/dex-net) Node on a GPU instance in the cloud and got a 12x speedup. For Motion Planning, we ran [Motion Planning Templates](https://robotics.cs.unc.edu/mpt/) on a 96-core cloud computer and got a 28x speedup. +In example applications, we used FogROS 2 to deploy compute-intensive ROS 2 nodes for SLAM, Grasp Planning, and Motion Planning to the cloud. For Visual SLAM, we ran an [ORB-SLAM 2](https://github.com/raulmur/ORB_SLAM2) Node on a multi-core cloud computer and we got a 2x speedup. For Grasp Planning, we ran the [Dex-Net](https://berkeleyautomation.github.io/dex-net/) Node on a GPU instance in the cloud and got a 12x speedup. For Motion Planning, we ran [Motion Planning Templates](https://robotics.cs.unc.edu/mpt/) on a 96-core cloud computer and got a 28x speedup. ![ORB-SLAM2](fogros2_orbslam2_example.svg) ![Dex-Net](fogros2_dexnet_example.svg) diff --git a/docs/cli.md b/docs/cli.md index bcd534f..a869a89 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,29 +1,31 @@ --- layout: page title: CLI -permalink: /cli/ +permalink: /cli +nav_order: 3 --- -# Command Line Interface (CLI) -FogROS2 uses Python entry points to extend the commands and verbs for ROS 2's CLI. Specifically, the `fogros2` package adds the `fog` command with three verbs, `list`, `connect` and `delete` for easy viewing of, interaction with, and termination of remote instances, respectively. More information about commands or verbs can be found by running `ros2 fog --help` or `ros2 fog --help`. +# Command Line Interface (CLI) +{: .no_toc } +FogROS 2 uses Python entry points to extend the commands and verbs for ROS 2's CLI. Specifically, the `fogros2` package adds the `fog` command with three verbs, `list`, `connect` and `delete` for easy viewing of, interaction with, and termination of remote instances, respectively. More information about commands or verbs can be found by running `ros2 fog --help` or `ros2 fog --help`.
CLI Commands {: .text-delta } - 1. TOC + - TOC {:toc}
## list -Prints information about existing FogROS2 instances. +Prints information about existing FogROS 2 instances. ### Usage **ros2 fog list** *[-h] [\-\-region REGION [REGION ...]]* ### Description -Prints a list of details -- instance name, cloud service provider (currently always AWS), region, instance type, region, id, IP address, SSH key, disk size, AMI, and state -- for existing FogROS2 instances. With no *REGION* specified, this command defaults to listing instances in the region set in the user's AWS configuration or in the corresponding environment variable. Otherwise, it lists all FogROS2 instances in *REGION* or in multiple regions if specified. +Prints a list of details -- instance name, cloud service provider (currently always AWS), region, instance type, region, id, IP address, SSH key, disk size, AMI, and state -- for existing FogROS 2 instances. With no *REGION* specified, this command defaults to listing instances in the region set in the user's AWS configuration or in the corresponding environment variable. Otherwise, it lists all FogROS 2 instances in *REGION* or in multiple regions if specified. ### Options **\-h, \-\-help** @@ -70,7 +72,7 @@ Opens a shell connection to an existing instance. **ros2 fog connect** *[\-h] [\-\-region [REGION [REGION ...]]] [\-\-user [USER]] NAME* ### Description -Connects via SSH to an existing FogROS2 instance with name *NAME*, allowing the user to run commands from a shell directly on the instance. FogROS2 instance names can be found using the `list` command. If no instances with name *NAME* are found in the specified region, this command will print "No matching instance found" and exit. +Connects via SSH to an existing FogROS 2 instance with name *NAME*, allowing the user to run commands from a shell directly on the instance. FogROS 2 instance names can be found using the `list` command. If no instances with name *NAME* are found in the specified region, this command will print "No matching instance found" and exit. ### Options **\-h, \-\-help** @@ -114,7 +116,7 @@ Terminates a running instance. **ros2 fog delete** *[\-h] [\-\-region [REGION [REGION ...]]] [\-\-dry-run] NAME* ### Description -Terminates an existing FogROS2 instance with name *NAME* and removes the key pair and data folder associated with the instance. If *NAME* is `all`, then all FogROS2 instances in the specified regions will be terminated. FogROS2 instance names can be found using the `list` command. If no instances with name *NAME* are found in the specified region, this command will print "No EC2 instances found with the specified name; check list to be sure name is correct! +Terminates an existing FogROS 2 instance with name *NAME* and removes the key pair and data folder associated with the instance. If *NAME* is `all`, then all FogROS 2 instances in the specified regions will be terminated. FogROS 2 instance names can be found using the `list` command. If no instances with name *NAME* are found in the specified region, this command will print "No EC2 instances found with the specified name; check list to be sure name is correct! No instances deleted" and exit. ### Options diff --git a/docs/cloud_robotics.md b/docs/cloud_robotics.md index 34d8dcc..2d766c6 100644 --- a/docs/cloud_robotics.md +++ b/docs/cloud_robotics.md @@ -1,6 +1,13 @@ +--- +layout: page +title: Cloud Robotics +permalink: /cloud_robotics +nav_order: 1 +--- + Cloud Robotics === -Cloud robotics encompasses many relations between the cloud and Robotics. Here we focus on what the cloud offers, explicitly focusing on the capabilities FogROS 2 can give robots by using the cloud. +Cloud robotics encompasses many relations between the cloud and robotics. Here we focus on what the cloud offers, explicitly focusing on the capabilities FogROS 2 can give robots by using the cloud. What is the cloud? --- @@ -20,9 +27,9 @@ The network latency to the cloud can be surprisingly short. The most crucial fa To understand bandwidth or bitrate, try out an internet speed test tool. -To understand the latency to the cloud, try out [cloudping.info]. This tool sends a small packet to the different data centers and measures the time before the response comes back. You can expect response times in the 10 to 40 ms range for nearby data centers. +To understand the latency to the cloud, try out [cloudping.info](https://cloudping.info/). This tool sends a small packet to the different data centers and measures the time before the response comes back. You can expect response times in the 10 to 40 ms range for nearby data centers. -With [cloudping.info], you can quickly understand which data center you should use for you cloud robotics applications. +With [cloudping.info](https://cloudping.info/), you can quickly understand which data center you should use for you cloud robotics applications. What is the edge? --- @@ -34,4 +41,4 @@ The fog encompasses everything between and including the cloud and the edge comp FogROS 2 and Cloud Robotics --- -FogROS 2 integrates ROS 2 applications with the cloud by streamlining the process of running ROS 2 nodes in the cloud and having them communicate with the robot. FogROS 2 takes care of: setting up cloud computers, installing ROS and dependencies, securing network communications, starting remote nodes, and more. As a user, you will need only to configure which nodes get deployed to which region and computer type. +FogROS 2 integrates ROS 2 applications with the cloud by streamlining the process of running ROS 2 nodes in the cloud and having them communicate with the robot. FogROS 2 takes care of setting up cloud computers, installing ROS and dependencies, securing network communications, starting remote nodes, and more. As a user, you will need only to configure which nodes get deployed to which region and computer type. diff --git a/docs/getting_started.md b/docs/getting_started.md index e3139fb..b99b6a6 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,3 +1,10 @@ +--- +layout: page +title: Getting Started +permalink: /getting_started +nav_order: 2 +--- + Getting Started === FogROS 2 streamlines the process of running parts of a ROS 2 application in the cloud. The main benefit is to speed up compute-intensive nodes by using cloud-based high-end computers and hardware acceleration. The only change typically needed is the launch configuration. @@ -6,18 +13,18 @@ Before describing how to configure a ROS 2 application to use FogROS 2, we will Region --- -The region is where the cloud computer is physically located. Since network latency increases as the distance between robot and cloud increases, selecting a physically close region is essential. A great tool to understand regions and latency is [cloudping.info]. Usually, it is best to select the region with the lowest latency (we will discuss in a moment). +The region is where the cloud computer is physically located. Since network latency increases as the distance between robot and cloud increases, selecting a physically close region is essential. A great tool to understand regions and latency is [cloudping.info](https://cloudping.info/). Usually, it is best to select the region with the lowest latency (see discussion below). Instance Type --- Cloud computers have different hardware specifications with a range of options: the number of CPU cores, amount of memory, types of included hardware accelerators (e.g., GPU, TPU, FPGA), and more. Here are a few example considerations: -Does the ROS node use a deep neural network and NOT have a GPU or TPU? If so, a cloud computer with a GPU or TPU could speed up computation significantly. -Does the ROS node make use of multi-core concurrency? If so, a cloud computer with many more cores than the robot has (e.g., 32-cores, 72-cores, 96-cores) could speed up computation significantly. -Could the ROS node use a specialized hardware accelerator such as an FPGA? If so, a cloud computer with the appropriate hardware could speed up computation significantly. -Are there more nodes running than the robot can handle? If so, hardware acceleration is less important than just getting enough computer cores to meet the demand. +- Does the ROS node use a deep neural network and NOT have a GPU or TPU? If so, a cloud computer with a GPU or TPU could speed up computation significantly. +- Does the ROS node make use of multi-core concurrency? If so, a cloud computer with many more cores than the robot has (e.g., 32-cores, 72-cores, 96-cores) could speed up computation significantly. +- Could the ROS node use a specialized hardware accelerator such as an FPGA? If so, a cloud computer with the appropriate hardware could speed up computation significantly. +- Are there more nodes running than the robot can handle? If so, hardware acceleration is less important than just getting enough computer cores to meet the demand. -The second part of instance type selection is determining the instance size, or how much computing is enough to best price/performance ratio (or to just fit into a budge). Higher-end instance types cost more money per hour, so ideally, one should select the minimum specification to meet performance criteria. For example, if the application gains no benefit beyond a 32-core computer, selecting a 92-core computer would waste money. How to best determine the instance size can come from a deep understanding of the application code or running a series of experiments with different instance sizes. +The second part of instance type selection is determining the instance size, or how much computing is needed to optimize the price/performance ratio (or to just fit into a budget). Higher-end instance types cost more money per hour, so ideally, one should select the minimum specification to meet performance criteria. For example, if the application gains no benefit beyond a 32-core computer, selecting a 92-core computer would waste money. How to best determine the instance size can come from a deep understanding of the application code or running a series of experiments with different instance sizes. Instance types and Regions --- From 38a24cbc9268e60cf569aa7a8d6458b991fa2d66 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Tue, 17 May 2022 22:20:36 -0700 Subject: [PATCH 14/30] Update about.md --- docs/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about.md b/docs/about.md index c028e62..d152598 100644 --- a/docs/about.md +++ b/docs/about.md @@ -5,7 +5,7 @@ permalink: /about nav_order: 0 --- -FogROS 2 is an open-source cloud-robotics pilot platform from UC Berkeley. Cloud computing using commercial clusters such as Amazon Web Services (AWS) is now fast enough to enable secure compute-intensive robot functions such as SLAM map building from video, grasp planning, and high dimensional motion planning to be performed in the Cloud using high-performance hardware and GPUs in near real-time. FogROS 2 offers ROS 2 functions to streamline the deployment of robot code. Developers do not need to change their code–they need only to specify an AWS configuration of computers that they want their code to run. FogROS 2 coordinates the details of initiating hardware instances, installing software and dependencies, securing robot-cloud communication, and launching cloud processes. +FogROS 2 is an open-source cloud-robotics pilot platform from UC Berkeley. Cloud computing using commercial clusters such as Amazon Web Services (AWS) is now fast enough to enable secure compute-intensive robot functions such as SLAM map building from video, grasp planning, and high dimensional motion planning to be performed in the Cloud using high-performance hardware and GPUs in near real-time. FogROS 2 offers ROS 2 functions to streamline the deployment of robot code. Developers do not need to change their code–they need only to specify an AWS configuration of computers that they want their code to run on. FogROS 2 coordinates the details of initiating hardware instances, installing software and dependencies, securing robot-cloud communication, and launching cloud processes. In example applications, we used FogROS 2 to deploy compute-intensive ROS 2 nodes for SLAM, Grasp Planning, and Motion Planning to the cloud. For Visual SLAM, we ran an [ORB-SLAM 2](https://github.com/raulmur/ORB_SLAM2) Node on a multi-core cloud computer and we got a 2x speedup. For Grasp Planning, we ran the [Dex-Net](https://berkeleyautomation.github.io/dex-net/) Node on a GPU instance in the cloud and got a 12x speedup. For Motion Planning, we ran [Motion Planning Templates](https://robotics.cs.unc.edu/mpt/) on a 96-core cloud computer and got a 28x speedup. From 05ddbad0b8778e0f9089811f77d54afcd5df619b Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Tue, 17 May 2022 22:26:28 -0700 Subject: [PATCH 15/30] Update cloud_robotics.md --- docs/cloud_robotics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud_robotics.md b/docs/cloud_robotics.md index 2d766c6..dd24b86 100644 --- a/docs/cloud_robotics.md +++ b/docs/cloud_robotics.md @@ -29,7 +29,7 @@ To understand bandwidth or bitrate, try out an internet speed test tool. To understand the latency to the cloud, try out [cloudping.info](https://cloudping.info/). This tool sends a small packet to the different data centers and measures the time before the response comes back. You can expect response times in the 10 to 40 ms range for nearby data centers. -With [cloudping.info](https://cloudping.info/), you can quickly understand which data center you should use for you cloud robotics applications. +With [cloudping.info](https://cloudping.info/), you can quickly understand which data center you should use for your cloud robotics applications. What is the edge? --- From 3785d7efbabb9f68e0ff1e10b09ccd203540beec Mon Sep 17 00:00:00 2001 From: Mike Danielczuk Date: Tue, 17 May 2022 22:32:16 -0700 Subject: [PATCH 16/30] add redirect from home to about --- docs/_config.yml | 1 + docs/{index.markdown => index.md} | 2 ++ 2 files changed, 3 insertions(+) rename docs/{index.markdown => index.md} (87%) diff --git a/docs/_config.yml b/docs/_config.yml index 4341b51..f42c012 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -31,6 +31,7 @@ github_username: BerkeleyAutomation remote_theme: just-the-docs/just-the-docs plugins: - jekyll-feed + - jekyll-redirect-from # Exclude from processing. # The following items will not be processed, by default. diff --git a/docs/index.markdown b/docs/index.md similarity index 87% rename from docs/index.markdown rename to docs/index.md index 0671507..1400b86 100644 --- a/docs/index.markdown +++ b/docs/index.md @@ -3,4 +3,6 @@ # To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults layout: home +redirect_to: + - /about --- From 62effb6937fff7430a490f462911d03f0db00adf Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 15:31:45 -0700 Subject: [PATCH 17/30] Create quickstart_instructions.md --- docs/quickstart_instructions.md | 135 ++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 docs/quickstart_instructions.md diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md new file mode 100644 index 0000000..574d015 --- /dev/null +++ b/docs/quickstart_instructions.md @@ -0,0 +1,135 @@ +--- +layout: page +title: Quickstart Instructions +permalink: /quickstart_instructions +nav_order: 4 +--- + +Quickstart Instructions +=== +This is a quick start guide for installing FogROS 2 (and ROS 2) and its requisites from scratch (e.g., in a VM). New contributors to the project can start here. +1. Install Ubuntu 20.04 or Ubuntu 22.04. See [here](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) for a tutorial. + +2. Upgrade +```bash +sudo apt update +sudo apt upgrade +``` + +3. Reboot + +4. Get UTF-8 locale installed + +``` +sudo apt install locales +sudo locale-gen en_US en_US.UTF-8 +sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 +export LANG=en_US.UTF-8 +``` + +5. Setup sources for ROS 2 (https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html) + +``` +sudo apt update +sudo apt install curl gnupg2 lsb-release +sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null +``` + +6. Install ROS 2 Packages (https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html) + +``` +sudo apt update +sudo apt install ros-rolling-desktop +``` + +7. Add env to startup + +``` +echo "source /opt/ros/rolling/setup.bash" >> ~/.bashrc +source /opt/ros/rolling/setup.bash +``` + +8. Choose and set a `ROS_DOMAIN_ID` (in range 0 to 101) (https://docs.ros.org/en/rolling/Concepts/About-Domain-ID.html) + +``` +export ROS_DOMAIN_ID=99 +echo 'export ROS_DOMAIN_ID=99' >> ~/.bashrc +``` +9. Install colcon and git + +``` +sudo apt install python3-colcon-common-extensions +sudo apt install git +``` + +10. Create a workspace + +``` +mkdir -p ~/fog_ws/src +``` + +11. Clone + +``` +cd ~/fog_ws/src +git clone -b humble https://github.com/BerkeleyAutomation/FogROS2.git +cp FogROS2/fogros2/configs/cyclonedds.ubuntu.$(lsb_release -rs | sed 's/\.//').xml ../cyclonedds.xml +``` + +12. Build + +``` +#If you see a warning like this, you are fine “On Ubuntu 22.04 this may generate deprecation warnings. These may be ignored.” +cd ~/fog_ws +colcon build +``` + +13. Install AWS CLI + +``` +sudo apt install awscli +``` + +14. Configure AWS Basic Settings. To run the next command, you need to have your [security credentials, an output format and AWS Region.](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) + +``` +aws configure +``` + +15. Install additional dependencies + +``` +sudo apt install python3-pip wireguard +pip install boto3 paramiko scp wgconfig +``` + +16. If using Ubuntu 22.04 + +``` +sudo apt install ros-rolling-rmw-cyclonedds-cpp +``` + +17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing. + +``` +cd ~/fog_ws +source install/setup.bash +export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp +export CYCLONEDDS_URI=file://$(pwd)/install/fogros2/share/fogros2/configs/cyclonedds.ubuntu.$(lsb_release -rs | sed 's/\.//').xml + +ros2 launch fogros2_examples talker.aws.launch.py +``` + +18. You are done. Refer to our [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://github.com/BerkeleyAutomation/FogROS2#command-line-interface), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker). + +``` +#To see the name of a FogROS2 instance +ros2 fog list + +#To delete a FogROS2 instance +ros2 fog delete [name] + +Typing CTRL-C kills the local instance (e.g., listener) the first time and then the cloud instance the second time + +``` From d93dc76a4c517538d5f93a1d62c8f893203b8745 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 15:39:39 -0700 Subject: [PATCH 18/30] Formatting Corrections --- docs/quickstart_instructions.md | 46 ++++++++++++--------------------- 1 file changed, 16 insertions(+), 30 deletions(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 574d015..31ef7a8 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -19,8 +19,7 @@ sudo apt upgrade 3. Reboot 4. Get UTF-8 locale installed - -``` +```bash sudo apt install locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 @@ -28,8 +27,7 @@ export LANG=en_US.UTF-8 ``` 5. Setup sources for ROS 2 (https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html) - -``` +```bash sudo apt update sudo apt install curl gnupg2 lsb-release sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg @@ -37,82 +35,71 @@ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-a ``` 6. Install ROS 2 Packages (https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html) - -``` +```bash sudo apt update sudo apt install ros-rolling-desktop ``` 7. Add env to startup - -``` +```bash echo "source /opt/ros/rolling/setup.bash" >> ~/.bashrc source /opt/ros/rolling/setup.bash ``` 8. Choose and set a `ROS_DOMAIN_ID` (in range 0 to 101) (https://docs.ros.org/en/rolling/Concepts/About-Domain-ID.html) - -``` +```bash export ROS_DOMAIN_ID=99 echo 'export ROS_DOMAIN_ID=99' >> ~/.bashrc ``` -9. Install colcon and git -``` +9. Install colcon and git +```bash sudo apt install python3-colcon-common-extensions sudo apt install git ``` 10. Create a workspace - -``` +```bash mkdir -p ~/fog_ws/src ``` 11. Clone - -``` +```bash cd ~/fog_ws/src git clone -b humble https://github.com/BerkeleyAutomation/FogROS2.git cp FogROS2/fogros2/configs/cyclonedds.ubuntu.$(lsb_release -rs | sed 's/\.//').xml ../cyclonedds.xml ``` 12. Build - -``` +```bash #If you see a warning like this, you are fine “On Ubuntu 22.04 this may generate deprecation warnings. These may be ignored.” cd ~/fog_ws colcon build ``` 13. Install AWS CLI - -``` +```bash sudo apt install awscli ``` 14. Configure AWS Basic Settings. To run the next command, you need to have your [security credentials, an output format and AWS Region.](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) - -``` +```bash aws configure ``` 15. Install additional dependencies - -``` +```bash sudo apt install python3-pip wireguard pip install boto3 paramiko scp wgconfig ``` 16. If using Ubuntu 22.04 - -``` +```bash sudo apt install ros-rolling-rmw-cyclonedds-cpp ``` 17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing. - -``` +```bash cd ~/fog_ws source install/setup.bash export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp @@ -122,8 +109,7 @@ ros2 launch fogros2_examples talker.aws.launch.py ``` 18. You are done. Refer to our [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://github.com/BerkeleyAutomation/FogROS2#command-line-interface), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker). - -``` +```bash #To see the name of a FogROS2 instance ros2 fog list From 5e3cc74960e49bce7c516cc5d592b26650e5dc5e Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 15:46:43 -0700 Subject: [PATCH 19/30] Update quickstart_instructions.md --- docs/quickstart_instructions.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 31ef7a8..ef4182e 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -98,7 +98,7 @@ pip install boto3 paramiko scp wgconfig sudo apt install ros-rolling-rmw-cyclonedds-cpp ``` -17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing. +17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing ```bash cd ~/fog_ws source install/setup.bash @@ -108,7 +108,7 @@ export CYCLONEDDS_URI=file://$(pwd)/install/fogros2/share/fogros2/configs/cyclon ros2 launch fogros2_examples talker.aws.launch.py ``` -18. You are done. Refer to our [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://github.com/BerkeleyAutomation/FogROS2#command-line-interface), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker). +18. You are done. Refer to our [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://github.com/BerkeleyAutomation/FogROS2#command-line-interface), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) ```bash #To see the name of a FogROS2 instance ros2 fog list @@ -117,5 +117,4 @@ ros2 fog list ros2 fog delete [name] Typing CTRL-C kills the local instance (e.g., listener) the first time and then the cloud instance the second time - ``` From ea6c10c465903860f0e69d2b4e72873697cd27b1 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 15:50:41 -0700 Subject: [PATCH 20/30] Update quickstart_instructions.md --- docs/quickstart_instructions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index ef4182e..11b19b5 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -99,6 +99,7 @@ sudo apt install ros-rolling-rmw-cyclonedds-cpp ``` 17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing + ```bash cd ~/fog_ws source install/setup.bash @@ -109,6 +110,7 @@ ros2 launch fogros2_examples talker.aws.launch.py ``` 18. You are done. Refer to our [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://github.com/BerkeleyAutomation/FogROS2#command-line-interface), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) + ```bash #To see the name of a FogROS2 instance ros2 fog list From 7228903b1664faf8aac7d5592e43c8dd0329b437 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 15:57:15 -0700 Subject: [PATCH 21/30] Update quickstart_instructions.md --- docs/quickstart_instructions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 11b19b5..29e89e8 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -110,7 +110,6 @@ ros2 launch fogros2_examples talker.aws.launch.py ``` 18. You are done. Refer to our [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://github.com/BerkeleyAutomation/FogROS2#command-line-interface), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) - ```bash #To see the name of a FogROS2 instance ros2 fog list From 56fbb2c4b651da88acae2942841eaf1ed1f12cc8 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 16:04:02 -0700 Subject: [PATCH 22/30] Update quickstart_instructions.md --- docs/quickstart_instructions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 29e89e8..49681d7 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -109,7 +109,8 @@ export CYCLONEDDS_URI=file://$(pwd)/install/fogros2/share/fogros2/configs/cyclon ros2 launch fogros2_examples talker.aws.launch.py ``` -18. You are done. Refer to our [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://github.com/BerkeleyAutomation/FogROS2#command-line-interface), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) +18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment + ```bash #To see the name of a FogROS2 instance ros2 fog list From 8cf2db9502f59398d03db487b180cecc642ba6f3 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 16:10:33 -0700 Subject: [PATCH 23/30] Formatting Updates --- docs/quickstart_instructions.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 49681d7..709e793 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -98,8 +98,7 @@ pip install boto3 paramiko scp wgconfig sudo apt install ros-rolling-rmw-cyclonedds-cpp ``` -17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing - +17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing ```bash cd ~/fog_ws source install/setup.bash @@ -109,8 +108,7 @@ export CYCLONEDDS_URI=file://$(pwd)/install/fogros2/share/fogros2/configs/cyclon ros2 launch fogros2_examples talker.aws.launch.py ``` -18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment - +18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment ```bash #To see the name of a FogROS2 instance ros2 fog list From 79e8fd0d73b1234aa0660e08b088e3923e5ac9c2 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Wed, 18 May 2022 16:41:38 -0700 Subject: [PATCH 24/30] Update quickstart_instructions.md --- docs/quickstart_instructions.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 709e793..7ae7401 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -98,7 +98,8 @@ pip install boto3 paramiko scp wgconfig sudo apt install ros-rolling-rmw-cyclonedds-cpp ``` -17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing +17. Run basic example. Note that the last command may take some time to complete especially the first time it is run. If your setup is correct, you should see the talker node publishing + ```bash cd ~/fog_ws source install/setup.bash @@ -108,7 +109,8 @@ export CYCLONEDDS_URI=file://$(pwd)/install/fogros2/share/fogros2/configs/cyclon ros2 launch fogros2_examples talker.aws.launch.py ``` -18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment +18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment + ```bash #To see the name of a FogROS2 instance ros2 fog list From 205c78edf2bc1f7c6d8a1590e2c4bf97aac07087 Mon Sep 17 00:00:00 2001 From: Karthik Dharmarajan Date: Thu, 19 May 2022 19:23:05 -0700 Subject: [PATCH 25/30] Added launch configuration documentation --- docs/launch_configuration.md | 180 +++++++++++++++++++++++++++++++++++ docs/video_compression.md | 6 ++ 2 files changed, 186 insertions(+) create mode 100644 docs/launch_configuration.md create mode 100644 docs/video_compression.md diff --git a/docs/launch_configuration.md b/docs/launch_configuration.md new file mode 100644 index 0000000..3504441 --- /dev/null +++ b/docs/launch_configuration.md @@ -0,0 +1,180 @@ +--- +layout: page +title: Launch Configuration +permalink: /launch_configuration +nav_order: 5 +--- + +# Launch Configuration +ROS 2 utilizes Python to create launch files which can specify what ROS 2 nodes should be launched. FogROS 2 utilizes these launch files to not only specify what nodes are launched, but where they are launched (i.e. on the robot or on the cloud machine). This page provides information about modifying existing launch files to work with FogROS 2 for deploying nodes to the cloud. + +## Robot Nodes +Robot nodes are ROS 2 nodes that are only running on the robot. There are no modifications necessary to the normal launch file to launch nodes that are running on the robot. + +## Cloud Nodes +Launching ROS 2 nodes in the cloud can be completed in 4 steps: +1. Add the following import to the top of the launch file: ```import fogros2``` + +2. Replace the ```LaunchDescription``` in the launch file with ```fogros2.FogROSLaunchDescription``` + +3. Specify AWS EC2 machine parameters by creating a ```fogros2.AWSCloudInstance``` object + +4. Replace all ```Node``` objects that need to be executed in the cloud with ```fogros2.CloudNode``` + +### fogros2.AWSCloudInstance + +#### Definition +```fogros2.AWSCloudInstance(ami_image, region="us-west-1", ec2_instance_type="t2.micro", disk_size=30)``` + +#### Description +An ```AWSCloudInstance``` is an object that represents an AWS EC2 instance that performs computation in the cloud. By specifying certain parameters for the machine, the AWS EC2 machine may be launched in different AWS regions or with different hardware. For help deciding some of the parameters, please visit the [Getting Started]({{site.baseurl}}/getting_started/) page. + +#### Parameters +```ami-image```: An AWS AMI is a template that is used to launch machines. The parameter itself is the Two recommended AMI images are 'ami-00f25057ddc9b310b' for Ubuntu 20.04 and 'ami-0b6030c78f8b2f076' for Ubuntu 22.04. Custom AMI images may be created to speed up deployment time, as any necessary dependencies can be installed in the AMI, so that every launch need not install all dependencies. For more information about AMIs, visit this [link](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html). + +```region```: The AWS region the machine will be launched in. By default, this is ```us-west-1```. + +```ec2_instance_type```: The type of machine that will be launched by AWS. For help deciding what machine to launch, please visit [Getting Started]({{site.baseurl}}/getting_started/). By default, this is a ```t2.micro``` instance, which is a lower compute free instance type. + +```disk_size```: The size of the disk of the EC2 instance in gigabytes. The default is 30GB. + +### fogros2.CloudNode + +#### Definition +```fogros2.CloudNode(machine, stream_topics=[], ...)``` + +#### Description +A ```CloudNode``` is a ROS 2 node that is executing in the cloud. + +#### Parameters +```machine```: machine is the ```fogros2.AWSCloudInstance``` created in step 3. + +```stream_topics```: stream_topics is used to specify any topics that are used for video streaming so that appropriate compression can be deployed. For more details, visit [Video Compression (H.264)]({{site.baseurl}}/video_compression/) + +Make sure to leave in any normal arguments that are a part of a normal ROS 2 node. An example will be provided to make the transition more clear. + +## Talker-Listener Example +Consider the following talker-listener launch file, which launches two nodes, where the listener subscribes to a topic and talker publishes to a topic (more details [here](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Py-Publisher-And-Subscriber.html)): +``` +from launch import LaunchDescription +from launch_ros.actions import Node + + +def generate_launch_description(): + ld = LaunchDescription() + + listener_node = Node( + package="fogros2_examples", executable="listener", output="screen" + ) + talker_node = Node( + package="fogros2_examples", executable="talker", output="screen" + ) + ld.add_action(talker_node) + ld.add_action(listener_node) + return ld +``` + +This section will show how to deploy the talker node onto the cloud, while the listener node stays on the robot. + +### Step 1: Add the following import to the top of the launch file: ```import fogros2``` +After running through this step, the launch file should now look like this: +``` +import fogros2 +from launch import LaunchDescription +from launch_ros.actions import Node + + +def generate_launch_description(): + ld = LaunchDescription() + + listener_node = Node( + package="fogros2_examples", executable="listener", output="screen" + ) + talker_node = Node( + package="fogros2_examples", executable="talker", output="screen" + ) + ld.add_action(talker_node) + ld.add_action(listener_node) + return ld +``` + +### Step 2: Replace the ```LaunchDescription``` in the launch file with ```fogros2.FogROSLaunchDescription``` +After running through this step, the launch file should now look like this: +``` +import fogros2 +from launch import LaunchDescription +from launch_ros.actions import Node + + +def generate_launch_description(): + ld = fogros2.FogROSLaunchDescription() + + listener_node = Node( + package="fogros2_examples", executable="listener", output="screen" + ) + talker_node = Node( + package="fogros2_examples", executable="talker", output="screen" + ) + ld.add_action(talker_node) + ld.add_action(listener_node) + return ld +``` + +### Step 3: Specify AWS EC2 machine parameters by creating a ```fogros2.AWSCloudInstance``` object +The ```AWSCloudInstance``` that needs to be created will be called machine, as follows: +```aws_machine = fogros2.AWSCloudInstance(region="us-west-1", ec2_instance_type="t2.micro", ami_image=ami-0b6030c78f8b2f076)``` + +The AWS region the machine will launch in is ```us-west-1``` with a t2.micro instance, which is low compute and free, and with an AMI that will make the machine run Ubuntu 22.04 (the AMI is one of the recommended ones stated earlier). + +Incorporating this into the launch file, +``` +import fogros2 +from launch import LaunchDescription +from launch_ros.actions import Node + + +def generate_launch_description(): + ld = fogros2.FogROSLaunchDescription() + aws_machine = fogros2.AWSCloudInstance( + region="us-west-1", + ec2_instance_type="t2.micro", + ami_image=ami-0b6030c78f8b2f076 + ) + listener_node = Node( + package="fogros2_examples", executable="listener", output="screen" + ) + talker_node = Node( + package="fogros2_examples", executable="talker", output="screen" + ) + ld.add_action(talker_node) + ld.add_action(listener_node) + return ld +``` + +### Step 4: Replace all ```Node``` objects that need to be executed in the cloud with ```fogros2.CloudNode``` + +Since the talker node will be deployed on the cloud, the modification will be to the talker node only. +``` +import fogros2 +from launch import LaunchDescription +from launch_ros.actions import Node + + +def generate_launch_description(): + ld = fogros2.FogROSLaunchDescription() + aws_machine = fogros2.AWSCloudInstance( + region="us-west-1", + ec2_instance_type="t2.micro", + ami_image=ami-0b6030c78f8b2f076 + ) + listener_node = Node( + package="fogros2_examples", executable="listener", output="screen" + ) + talker_node = fogros2.CloudNode( + package="fogros2_examples", executable="talker", output="screen", machine=aws_machine + ) + ld.add_action(talker_node) + ld.add_action(listener_node) + return ld +``` +Notice that in this example, the machine was set to the aws_machine that was created earlier. \ No newline at end of file diff --git a/docs/video_compression.md b/docs/video_compression.md new file mode 100644 index 0000000..4b5c664 --- /dev/null +++ b/docs/video_compression.md @@ -0,0 +1,6 @@ +--- +layout: page +title: Video Compression (H.264) +permalink: /video_compression +nav_order: 6 +--- \ No newline at end of file From 54114eefc9fb0fff48a24ec4d511327cf2a89459 Mon Sep 17 00:00:00 2001 From: Karthik Dharmarajan Date: Fri, 20 May 2022 00:47:46 -0700 Subject: [PATCH 26/30] Added H.264 and video compression documentation : --- docs/launch_configuration.md | 4 ++-- docs/video_compression.md | 35 ++++++++++++++++++++++++++++++++++- 2 files changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/launch_configuration.md b/docs/launch_configuration.md index 3504441..7ca4c65 100644 --- a/docs/launch_configuration.md +++ b/docs/launch_configuration.md @@ -34,7 +34,7 @@ An ```AWSCloudInstance``` is an object that represents an AWS EC2 instance that ```region```: The AWS region the machine will be launched in. By default, this is ```us-west-1```. -```ec2_instance_type```: The type of machine that will be launched by AWS. For help deciding what machine to launch, please visit [Getting Started]({{site.baseurl}}/getting_started/). By default, this is a ```t2.micro``` instance, which is a lower compute free instance type. +```ec2_instance_type```: The type of machine that will be launched by AWS. For help deciding what machine to launch, please visit [Getting Started]({{site.baseurl}}/getting_started). By default, this is a ```t2.micro``` instance, which is a lower compute free instance type. ```disk_size```: The size of the disk of the EC2 instance in gigabytes. The default is 30GB. @@ -49,7 +49,7 @@ A ```CloudNode``` is a ROS 2 node that is executing in the cloud. #### Parameters ```machine```: machine is the ```fogros2.AWSCloudInstance``` created in step 3. -```stream_topics```: stream_topics is used to specify any topics that are used for video streaming so that appropriate compression can be deployed. For more details, visit [Video Compression (H.264)]({{site.baseurl}}/video_compression/) +```stream_topics```: stream_topics is used to specify any topics that are used for video streaming so that appropriate compression can be deployed. For more details, visit [Video Compression (H.264)]({{site.baseurl}}/video_compression). Make sure to leave in any normal arguments that are a part of a normal ROS 2 node. An example will be provided to make the transition more clear. diff --git a/docs/video_compression.md b/docs/video_compression.md index 4b5c664..01b56c5 100644 --- a/docs/video_compression.md +++ b/docs/video_compression.md @@ -3,4 +3,37 @@ layout: page title: Video Compression (H.264) permalink: /video_compression nav_order: 6 ---- \ No newline at end of file +--- + +# Video Compression + +One consideration that may pop up when utilizing the cloud for computation is streaming video or images for computer vision. Due to the large size of an uncompressed image, there may be adverse effects to round trip time or frames per second when streaming video in a bandwidth constrained environment. FogROS 2 is able to utilize ```image_transport``` to set up encoder and decoder nodes that compress and decompress the raw images. In particular, JPEG/PNG compression and the Theora compression format are supported through the ```image_transport_plugins```, and FogROS 2 adds additional support for H.264 encoding in ROS 2. H.264 decoding is provided through another community package. + +Note that out of the options listed above only PNG is lossless. If the computer vision algorithm used in the cloud is not robust to the the lossy output of H.264, JPEG, Theora, then it is recommended to use PNG compression. Note that the encoding/decoding computational power increases from JPEG, Theora, to H.264, but the compression efficiency also increases in that order. + +## PNG/JPEG/Theora Setup + +Download the ```image_transport_plugins``` package by running ```sudo apt-get install ros--image-transport-plugins```, where `````` should be replaced by the ROS distribution installed. + +## H.264 Setup + +Since the H.264 image transport is not a publicly available ROS package, the repositories necessary will have to be manually downloaded. + +1. Download the repository [linked here](https://github.com/BerkeleyAutomation/FogROS2/tree/main) using the command ```git clone -b main --recurse-submodules https://github.com/BerkeleyAutomation/FogROS2```. + +2. Place only the subdirectories `ros2_h264_encoder` and `h264_image_transport` in the ROS 2 workspace. Everything else should be deleted. + +3. Install dependencies using the following command +``` +sudo apt-get install libavdevice-dev libavformat-dev libavcodec-dev libavutil-dev libswscale-dev libx264-dev +``` + +## General Setup + +1. Identify all topics that need to be compressed. For sake of example, the topic `/camera/image_raw` will be used. + +2. When modifying an existing launch file, and in Step 4 of this [guide]({{site.baseurl}}/launch_configuration), add a `stream_topics` argument to the `fogros2.CloudNode`. The `stream_topics` argument is a list of tuples, where the first argument in the tuple is the topic name, and the second argument is the transport/compression type. +For the `/camera/image_raw` example, if H.264 was desired, the argument to `fogros2.CloudNode` would be `stream_topics=[('/camera/image_raw', 'h264')]`. Repeat this step for any/all topics that should be compressed, and add each topic as a separate tuple in the `stream_topics` list. +Valid options for the 2nd element of a given tuple are `h264`, `theora`, or `compressed`. `compressed` will default to JPEG compression, so the ROS 2 parameter of `/compressed/format` needs to be changed to 'png'. More details are [here](http://wiki.ros.org/compressed_image_transport). + +3. The node on the cloud that is expecting to receive the raw images should have the listener's topic name changed from ``to `/cloud`. For example, the node that is subscribing to `/camera/image_raw` in the cloud should now listen for `/camera/image_raw/cloud`. This is the only change in the code that will have to be done to reduce any potential namespace conflicts. This step may become optional when automatic topic remapping is implemented. \ No newline at end of file From 8f74ed7dc1e3174fc439916ab89e8ee054505385 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Sun, 22 May 2022 13:12:43 -0700 Subject: [PATCH 27/30] Vidoe links, CLI text, minor changes --- docs/quickstart_instructions.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 7ae7401..4a6320a 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -7,7 +7,7 @@ nav_order: 4 Quickstart Instructions === -This is a quick start guide for installing FogROS 2 (and ROS 2) and its requisites from scratch (e.g., in a VM). New contributors to the project can start here. +This is a quick start guide for installing FogROS 2 (and ROS 2) and its requisites from scratch (e.g., in a VM). New contributors to the project can start here. You can also watch our video tutorials here: [part 1](https://youtu.be/IfR0JjOytuE) and [part 2](https://youtu.be/tXH0kxx7LqU) 1. Install Ubuntu 20.04 or Ubuntu 22.04. See [here](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) for a tutorial. 2. Upgrade @@ -17,6 +17,9 @@ sudo apt upgrade ``` 3. Reboot +```bash +reboot +``` 4. Get UTF-8 locale installed ```bash @@ -109,7 +112,11 @@ export CYCLONEDDS_URI=file://$(pwd)/install/fogros2/share/fogros2/configs/cyclon ros2 launch fogros2_examples talker.aws.launch.py ``` -18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment +18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment. + +Next we’ll terminate the demo by typing CTRL-C twice. The first one terminates the robot node, the second one terminates the cloud node. + +We can see the cloud computer that FogROS 2 launched for us using the FogROS command-line interface or CLI. “ros2 fog list” shows that we have one running instance with the name XXX. Finally, we terminate the instance so that we are no longer being charged for it by running “ros2 fog delete XXX”. You can verify that it is being deleted and by running “ros2 fog list” again. Observe the “status shutting down” line. After a short while, running ros2 fog list will show nothing, indicating that the instance is terminated and you are no longer being charged. ```bash #To see the name of a FogROS2 instance From d726f75d8fd75e1447f7982c9d91969f9dc5c265 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Thu, 16 Jun 2022 18:30:59 -0700 Subject: [PATCH 28/30] Set Youtube Videos to Embed --- docs/quickstart_instructions.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 4a6320a..f9fe266 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -7,7 +7,14 @@ nav_order: 4 Quickstart Instructions === -This is a quick start guide for installing FogROS 2 (and ROS 2) and its requisites from scratch (e.g., in a VM). New contributors to the project can start here. You can also watch our video tutorials here: [part 1](https://youtu.be/IfR0JjOytuE) and [part 2](https://youtu.be/tXH0kxx7LqU) +This is a quick start guide for installing FogROS 2 (and ROS 2) and its requisites from scratch (e.g., in a VM). New contributors to the project can start here. You can also watch our video tutorials here: + + +and + + + + 1. Install Ubuntu 20.04 or Ubuntu 22.04. See [here](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) for a tutorial. 2. Upgrade From f0534c27416ddc5fd16d92aa1a8124d367d401dd Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Mon, 27 Jun 2022 11:33:49 -0700 Subject: [PATCH 29/30] Embed Docker and Native Install Videos Adding this here since there are no separate pages for Docker and Native Installation --- docs/quickstart_instructions.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index f9fe266..543731a 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -119,7 +119,7 @@ export CYCLONEDDS_URI=file://$(pwd)/install/fogros2/share/fogros2/configs/cyclon ros2 launch fogros2_examples talker.aws.launch.py ``` -18. You are done. Refer to other relevant pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment. +18. You are done. Refer to other relevant github pages including [README](https://github.com/BerkeleyAutomation/FogROS2/blob/main/README.md) for additional information including [Command Line Interface commands](https://berkeleyautomation.github.io/FogROS2/cli), which allow you do a lot with your cloud instances from the command line, and [Docker installation](https://github.com/BerkeleyAutomation/FogROS2#docker) for those who want to use FogROS2 in a Docker environment. Next we’ll terminate the demo by typing CTRL-C twice. The first one terminates the robot node, the second one terminates the cloud node. @@ -134,3 +134,12 @@ ros2 fog delete [name] Typing CTRL-C kills the local instance (e.g., listener) the first time and then the cloud instance the second time ``` +19. Our video tutorials for Docker installation and native installations are include below. + +Docker: + + +Native Installation: + + + From 93e1b99f9fc41243c145639394abef6bf47f2774 Mon Sep 17 00:00:00 2001 From: Simeon ADEBOLA <39528961+SimeonOA@users.noreply.github.com> Date: Mon, 27 Jun 2022 11:50:35 -0700 Subject: [PATCH 30/30] Update quickstart_instructions.md --- docs/quickstart_instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstart_instructions.md b/docs/quickstart_instructions.md index 543731a..f8a8657 100644 --- a/docs/quickstart_instructions.md +++ b/docs/quickstart_instructions.md @@ -134,7 +134,7 @@ ros2 fog delete [name] Typing CTRL-C kills the local instance (e.g., listener) the first time and then the cloud instance the second time ``` -19. Our video tutorials for Docker installation and native installations are include below. +19. Our video tutorials for Docker installation and a native installation are included below. Docker: