From d3c8436309086dd0516482b87950d8c3a7492449 Mon Sep 17 00:00:00 2001 From: Evan Palmer Date: Sat, 13 Apr 2024 02:04:34 -0700 Subject: [PATCH 01/14] Added docs --- .devcontainer/documentation/Dockerfile | 12 + .devcontainer/documentation/devcontainer.json | 22 + .devcontainer/nouveau/devcontainer.json | 8 +- .devcontainer/nvidia/devcontainer.json | 8 +- blue_demos/CMakeLists.txt | 26 + blue_demos/LICENSE | 17 + blue_demos/package.xml | 28 + docs/.gitignore | 20 + docs/babel.config.js | 3 + docs/docs/installation.mdx | 72 + docs/docs/overview.mdx | 53 + docs/docs/tutorials/_category_.json | 4 + docs/docs/tutorials/control.mdx | 4 + docs/docs/tutorials/localization.mdx | 4 + docs/docs/tutorials/simulation.mdx | 4 + docs/docs/tutorials/teleop.mdx | 7 + docs/docs/welcome.mdx | 49 + docs/docusaurus.config.js | 76 + docs/package-lock.json | 17019 ++++++++++++++++ docs/package.json | 54 + docs/sidebars.js | 7 + docs/src/components/Topic.jsx | 25 + docs/src/components/Vehicle.jsx | 22 + docs/src/css/cards.scss | 13 + docs/src/css/custom.scss | 52 + docs/src/css/fonts-and-colors.scss | 115 + docs/src/css/header.scss | 39 + docs/src/css/typography.scss | 5 + docs/static/.nojekyll | 0 docs/static/img/docusaurus-social-card.jpg | Bin 0 -> 55746 bytes docs/static/img/docusaurus.png | Bin 0 -> 5142 bytes docs/static/img/favicon.ico | Bin 0 -> 3626 bytes docs/static/img/logo.svg | 1 + .../static/img/undraw_docusaurus_mountain.svg | 171 + docs/static/img/undraw_docusaurus_react.svg | 170 + docs/static/img/undraw_docusaurus_tree.svg | 40 + 36 files changed, 18140 insertions(+), 10 deletions(-) create mode 100644 .devcontainer/documentation/Dockerfile create mode 100644 .devcontainer/documentation/devcontainer.json create mode 100644 blue_demos/CMakeLists.txt create mode 100644 blue_demos/LICENSE create mode 100644 blue_demos/package.xml create mode 100644 docs/.gitignore create mode 100644 docs/babel.config.js create mode 100644 docs/docs/installation.mdx create mode 100644 docs/docs/overview.mdx create mode 100644 docs/docs/tutorials/_category_.json create mode 100644 docs/docs/tutorials/control.mdx create mode 100644 docs/docs/tutorials/localization.mdx create mode 100644 docs/docs/tutorials/simulation.mdx create mode 100644 docs/docs/tutorials/teleop.mdx create mode 100644 docs/docs/welcome.mdx create mode 100644 docs/docusaurus.config.js create mode 100644 docs/package-lock.json create mode 100644 docs/package.json create mode 100644 docs/sidebars.js create mode 100644 docs/src/components/Topic.jsx create mode 100644 docs/src/components/Vehicle.jsx create mode 100644 docs/src/css/cards.scss create mode 100644 docs/src/css/custom.scss create mode 100644 docs/src/css/fonts-and-colors.scss create mode 100644 docs/src/css/header.scss create mode 100644 docs/src/css/typography.scss create mode 100644 docs/static/.nojekyll create mode 100644 docs/static/img/docusaurus-social-card.jpg create mode 100644 docs/static/img/docusaurus.png create mode 100644 docs/static/img/favicon.ico create mode 100644 docs/static/img/logo.svg create mode 100644 docs/static/img/undraw_docusaurus_mountain.svg create mode 100644 docs/static/img/undraw_docusaurus_react.svg create mode 100644 docs/static/img/undraw_docusaurus_tree.svg diff --git a/.devcontainer/documentation/Dockerfile b/.devcontainer/documentation/Dockerfile new file mode 100644 index 00000000..dc13a7e4 --- /dev/null +++ b/.devcontainer/documentation/Dockerfile @@ -0,0 +1,12 @@ +FROM node:20 + +RUN apt-get -q update \ + && apt-get -q -y upgrade \ + && apt-get install sudo \ + && apt-get autoremove -y \ + && apt-get clean -y \ + && rm -rf /var/lib/apt/lists/* + +ARG USERNAME=node +RUN echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \ + && chmod 0440 /etc/sudoers.d/$USERNAME diff --git a/.devcontainer/documentation/devcontainer.json b/.devcontainer/documentation/devcontainer.json new file mode 100644 index 00000000..48a8b692 --- /dev/null +++ b/.devcontainer/documentation/devcontainer.json @@ -0,0 +1,22 @@ +{ + "name": "Documentation", + "build": { + "dockerfile": "Dockerfile" + }, + "remoteUser": "node", + "customizations": { + "vscode": { + "settings": { + "files.insertFinalNewline": true, + "files.trimTrailingWhitespace": true, + "editor.formatOnSave": true, + "editor.tabSize": 2, + "editor.rulers": [80] + }, + "extensions": [ + "esbenp.prettier-vscode", + "unifiedjs.vscode-mdx" + ] + } + } +} diff --git a/.devcontainer/nouveau/devcontainer.json b/.devcontainer/nouveau/devcontainer.json index 44b1e52a..13feab28 100644 --- a/.devcontainer/nouveau/devcontainer.json +++ b/.devcontainer/nouveau/devcontainer.json @@ -1,5 +1,5 @@ { - "name": "Blue Nouveau Dev Container", + "name": "Nouveau Dev Container", "dockerFile": "Dockerfile", "context": "../..", "workspaceMount": "source=${localWorkspaceFolder},target=/home/blue/ws_blue/src/blue,type=bind", @@ -26,16 +26,14 @@ "ms-azuretools.vscode-docker", "ms-python.python", "njpwerner.autodocstring", - "ms-vscode.cpptools", "redhat.vscode-xml", "redhat.vscode-yaml", "smilerobotics.urdf", - "DavidAnson.vscode-markdownlint", "esbenp.prettier-vscode", - "xaver.clang-format", "charliermarsh.ruff", "ms-python.black-formatter", - "josetr.cmake-language-support-vscode" + "josetr.cmake-language-support-vscode", + "unifiedjs.vscode-mdx" ] } } diff --git a/.devcontainer/nvidia/devcontainer.json b/.devcontainer/nvidia/devcontainer.json index 5493600d..03fecdb8 100644 --- a/.devcontainer/nvidia/devcontainer.json +++ b/.devcontainer/nvidia/devcontainer.json @@ -1,5 +1,5 @@ { - "name": "Blue NVIDIA Dev Container", + "name": "NVIDIA Dev Container", "dockerFile": "Dockerfile", "context": "../..", "workspaceMount": "source=${localWorkspaceFolder},target=/home/blue/ws_blue/src/blue,type=bind", @@ -30,16 +30,14 @@ "ms-azuretools.vscode-docker", "ms-python.python", "njpwerner.autodocstring", - "ms-vscode.cpptools", "redhat.vscode-xml", "redhat.vscode-yaml", "smilerobotics.urdf", - "DavidAnson.vscode-markdownlint", "esbenp.prettier-vscode", - "xaver.clang-format", "charliermarsh.ruff", "ms-python.black-formatter", - "josetr.cmake-language-support-vscode" + "josetr.cmake-language-support-vscode", + "unifiedjs.vscode-mdx" ] } } diff --git a/blue_demos/CMakeLists.txt b/blue_demos/CMakeLists.txt new file mode 100644 index 00000000..cc5f0056 --- /dev/null +++ b/blue_demos/CMakeLists.txt @@ -0,0 +1,26 @@ +cmake_minimum_required(VERSION 3.8) +project(blue_demos) + +if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang") + add_compile_options(-Wall -Wextra -Wpedantic) +endif() + +# find dependencies +find_package(ament_cmake REQUIRED) +# uncomment the following section in order to fill in +# further dependencies manually. +# find_package( REQUIRED) + +if(BUILD_TESTING) + find_package(ament_lint_auto REQUIRED) + # the following line skips the linter which checks for copyrights + # comment the line when a copyright and license is added to all source files + set(ament_cmake_copyright_FOUND TRUE) + # the following line skips cpplint (only works in a git repo) + # comment the line when this package is in a git repo and when + # a copyright and license is added to all source files + set(ament_cmake_cpplint_FOUND TRUE) + ament_lint_auto_find_test_dependencies() +endif() + +ament_package() diff --git a/blue_demos/LICENSE b/blue_demos/LICENSE new file mode 100644 index 00000000..30e8e2ec --- /dev/null +++ b/blue_demos/LICENSE @@ -0,0 +1,17 @@ +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/blue_demos/package.xml b/blue_demos/package.xml new file mode 100644 index 00000000..18a74977 --- /dev/null +++ b/blue_demos/package.xml @@ -0,0 +1,28 @@ + + + + + blue_demos + 0.0.1 + A collection of demonstrations that show how to use Blue + + Evan Palmer + MIT + + https://github.com/Robotic-Decision-Making-Lab/blue.git + https://github.com/Robotic-Decision-Making-Lab/blue/issues + + Evan Palmer + + ament_cmake + + ament_lint_auto + + ament_cmake_copyright + ament_cmake_lint_cmake + ament_cmake_xmllint + + + ament_cmake + + diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..b2d6de30 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,20 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/docs/babel.config.js b/docs/babel.config.js new file mode 100644 index 00000000..e00595da --- /dev/null +++ b/docs/babel.config.js @@ -0,0 +1,3 @@ +module.exports = { + presets: [require.resolve('@docusaurus/core/lib/babel/preset')], +}; diff --git a/docs/docs/installation.mdx b/docs/docs/installation.mdx new file mode 100644 index 00000000..a1ad5fec --- /dev/null +++ b/docs/docs/installation.mdx @@ -0,0 +1,72 @@ +--- +sidebar_position: 3 +--- + +# Installation + +Blue is currently supported on Linux and is available for the ROS distributions +Humble and Iron. Blue can be installed from source or using one of +the provided Docker images. If you plan to use Blue for simulation and have +a system with limited compute power, we recommend installing Blue from source. +For all other cases, we recommend installing Blue using Docker. + +## Docker installation + +Prior to installing Blue using Docker, make sure that Docker is installed on +your system and that you are logged into the GitHub Container Registery. If +Docker is not installed, you may follow the instructions provided +[here](https://docs.docker.com/get-docker/). If you are not already logged into +the GitHub Container Registery, please do so by following the instructions +provided [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). +Once you have successfully installed Docker and logged into the GitHub Container +Registery, you can install Blue by pulling one of the provided [Docker +images](https://github.com/Robotic-Decision-Making-Lab/blue/pkgs/container/blue). +A complete list of the provided images is documented below (where `*` should be +replaced with the desired ROS distrubtion, e.g., `humble-robot`): + +| Supported ROS Versions | Image Tag | Build Architectures | Description | +| ---------------------- | --------- | ------------------- | ----------- | +| Humble, Iron | *-robot | `amd64`, `arm64` | A bare-bones image that includes all dependencies without simulation or visualization features. This can be used to deploy Blue to hardware. | +| Humble, Iron | *-desktop | `amd64` | Image that includes all dependencies, including simulation and visualization features. This can be used for development, testing, and top-side deployment. | +| Humble, Iron | *-desktop-nvidia | `amd64` | Extension of the `*-desktop` image that provides support for NVIDIA GPU drivers. This image is *strongly* recommended for systems that have an NVIDIA GPU, and requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). | + +If you plan to use either the `*-desktop` or `*-desktop-nvidia` images, you may +use the provided [Docker Compose scripts](https://github.com/Robotic-Decision-Making-Lab/blue/tree/main/.docker/compose) +to install and run Blue. For instance, to pull and run the `iron-desktop` image, +first run the command: + +```bash +wget https://raw.githubusercontent.com/Robotic-Decision-Making-Lab/blue/iron/.docker/compose/nouveau-desktop.yaml && \ +docker compose -f nouveau-desktop.yaml up +``` + +then in a new tab, enter the container by running + +```bash +docker exec -it /bin/bash +``` + +where `` should be replaced with the name of the container that was +created. + +### Development container + +We recommend using one of the provided Visual Studio Code +[development containers](https://github.com/Robotic-Decision-Making-Lab/blue/tree/main/.devcontainer) +to implement and test your own packages. These containers use the `*-desktop` +and `*-desktop-nvidia` images as base images. To use the development containers, +first verify that you can run Visual Studio Code inside a Docker container by +following the tutorial provided [here](https://code.visualstudio.com/docs/devcontainers/tutorial). +Once you have successfully verified that you can run Visual Studio Code inside a +Docker container, open the Blue repository in Visual Studio Code and select the option +to reopen the folder inside a container when prompted. This will automatically +build the development container and install all necessary dependencies. Once the +container is built, you can start developing your own packages! + +## Source installation + +We recommend using the project [Dockerfile](https://github.com/Robotic-Decision-Making-Lab/blue/blob/main/.docker/Dockerfile) +(beginning at the `robot` stage) for complete source installation details. This +installation may be customized according to your specific needs. For example, +if you do not plan to use the simulation environment, you may forego installing +Gazebo and its dependencies. diff --git a/docs/docs/overview.mdx b/docs/docs/overview.mdx new file mode 100644 index 00000000..ab1d0d06 --- /dev/null +++ b/docs/docs/overview.mdx @@ -0,0 +1,53 @@ +--- +sidebar_position: 2 +--- + +import Vehicle from '@site/src/components/Vehicle'; + +# Overview + +Blue provides a set of tools to help you test and deploy software for underwater +vehicles. This is accomplished through the following features: + +1. **Simulation using Gazebo**: Vehicle models and configurations have been + created for Gazebo. We have found that Gazebo provides a good representation + of how the vehicle will behave in the real world. +2. **CI/CD pipelines**: Blue implements CI/CD pipelines to help you deploy your + software in the same environment that you performed development and testing + in. Docker images are built for the `amd64` and `arm64` CPU architectures so + that you can easily deploy your software to a variety of hardware platforms. +3. **Development environment**: Blue provides a development environment that + includes all of the tools you need to develop software for underwater + vehicles, such as ROS 2, Gazebo, linters, and formatters. This helps you + avoid spending resources setting up your development environment and focus on + writing your robotics algorithms 😀 +4. **Custom control and localization algorithms**: Blue supports custom +controllers implemented using [auv_controllers](https://github.com/Robotic-Decision-Making-Lab/auv_controllers) +and localization algorithms implemented using [marine_localization](https://github.com/Robotic-Decision-Making-Lab/marine_localization). + +## Workflow + +Under construction! + +## Supported Vehicles + +Several vehicle models have been implemented and tested with Blue in +**simulation** and on **hardware**. These vehicles include: + +
+ + The BlueROV2 is a popular lightweight underwater vehicle made by [Blue Robotics](https://bluerobotics.com/) + that is used for hobby, research, and commercial applications. + + + The BlueROV2 Heavy is an extension to the BlueROV2 made by [Blue Robotics](https://bluerobotics.com/) + that includes additional thrusters and a larger frame to improve the + vehicle's manueverability. + + + The BlueROV2 Heavy Reach modifies the BlueROV2 Heavy by moving the + thrusters located on the upper chassis to the lower chassis. This was + proposed by [Reach Robotics](https://reachrobotics.com/) to enable + integration of a small manipulator for intervention tasks. + +
diff --git a/docs/docs/tutorials/_category_.json b/docs/docs/tutorials/_category_.json new file mode 100644 index 00000000..b9dada94 --- /dev/null +++ b/docs/docs/tutorials/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tutorials", + "position": 4 +} diff --git a/docs/docs/tutorials/control.mdx b/docs/docs/tutorials/control.mdx new file mode 100644 index 00000000..649b1136 --- /dev/null +++ b/docs/docs/tutorials/control.mdx @@ -0,0 +1,4 @@ +--- +sidebar_position: 2 +title: Running Custom Controllers +--- diff --git a/docs/docs/tutorials/localization.mdx b/docs/docs/tutorials/localization.mdx new file mode 100644 index 00000000..9da50f5b --- /dev/null +++ b/docs/docs/tutorials/localization.mdx @@ -0,0 +1,4 @@ +--- +sidebar_position: 3 +title: Integrating Localization +--- diff --git a/docs/docs/tutorials/simulation.mdx b/docs/docs/tutorials/simulation.mdx new file mode 100644 index 00000000..1e8ab31d --- /dev/null +++ b/docs/docs/tutorials/simulation.mdx @@ -0,0 +1,4 @@ +--- +sidebar_position: 1 +title: Launching the Simulator +--- diff --git a/docs/docs/tutorials/teleop.mdx b/docs/docs/tutorials/teleop.mdx new file mode 100644 index 00000000..586eea00 --- /dev/null +++ b/docs/docs/tutorials/teleop.mdx @@ -0,0 +1,7 @@ +--- +sidebar_position: 4 +title: Teleoperation +--- + +# Teleoperation + diff --git a/docs/docs/welcome.mdx b/docs/docs/welcome.mdx new file mode 100644 index 00000000..bcb9453b --- /dev/null +++ b/docs/docs/welcome.mdx @@ -0,0 +1,49 @@ +--- +sidebar_position: 1 +title: Welcome! +hide_table_of_contents: true +slug: / +--- + +import Link from "@docusaurus/Link"; +import CodeBlock from '@theme/CodeBlock'; +import Topic from '@site/src/components/Topic'; + +# 🌊 Blue Documentation + +
+
+
+

+ [**Blue**](https://github.com/Robotic-Decision-Making-Lab/blue) is an + open source ROS 2 pipeline designed to support development, testing, and + sim-to-real deployment of underwater vehicles. Get started with Blue by + [installing the project](/installation) or following our + [first tutorial](/tutorials/simulation). If you have any questions + regarding usage of Blue, please ask a question on our [Discussions](https://github.com/Robotic-Decision-Making-Lab/blue/discussions) + board! + + If you find Blue to be helpful in your work, please consider citing our + paper: +

+
+ +{`@inproceedings{palmer2024angler, + author={Palmer, Evan and Holm, Christopher and Hollinger, Geoffrey}, + title={{Angler: An Autonomy Framework for Intervention Tasks with Lightweight Underwater Vehicle Manipulator Systems}}, + booktitle={IEEE International Conference on Robotics and Automation}, + year={2024} +}`} + +
+
+