Added user documentation

.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

.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"
+      ]
+    }
+  }
+}

.devcontainer/nouveau/Dockerfile

@@ -1,4 +1,4 @@
-FROM ghcr.io/robotic-decision-making-lab/blue:rolling-desktop
+FROM ghcr.io/robotic-decision-making-lab/blue:iron-desktop
 
 # Install ROS dependencies
 # This is done in a previous stage, but we include it again here in case anyone wants to
@@ -17,9 +17,9 @@ RUN sudo apt-get -q update \
     && sudo rm -rf /var/lib/apt/lists/*
 
 # Install debugging/linting Python packages
-COPY --chown=$USER_UID:$USER_GID requirements-dev.txt .
-RUN python3 -m pip install -r requirements-dev.txt \
-    && rm -rf requirements-dev.txt
+RUN python3 -m pip install \
+    pre-commit \
+    mypy
 
 # Disable the setuputils installation warning
 # This prevents us from needing to pin the setuputils version (which doesn't always work)

.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,13 @@
         "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"
       ]
     }
   }

.devcontainer/nvidia/Dockerfile

@@ -10,17 +10,16 @@ WORKDIR $USER_WORKSPACE
 COPY --chown=$USER_UID:$USER_GID . src/blue
 RUN sudo apt-get -q update \
     && sudo apt-get -q -y upgrade \
-    && vcs import src < src/blue/blue.repos \
     && rosdep update \
     && rosdep install -y --from-paths src --ignore-src --rosdistro ${ROS_DISTRO} --skip-keys="gz-transport12 gz-sim7 gz-math7 gz-msgs9 gz-plugin2" \
     && sudo apt-get autoremove -y \
     && sudo apt-get clean -y \
     && sudo rm -rf /var/lib/apt/lists/*
 
 # Install debugging/linting Python packages
-COPY --chown=$USER_UID:$USER_GID requirements-dev.txt .
-RUN python3 -m pip install -r requirements-dev.txt \
-    && rm -rf requirements-dev.txt
+RUN python3 -m pip install \
+    pre-commit \
+    mypy
 
 # Disable the setuputils installation warning
 # This prevents us from needing to pin the setuputils version (which doesn't always work)

.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,13 @@
         "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"
       ]
     }
   }

.dockerignore

@@ -4,9 +4,8 @@
 # Except the following
 !blue_bringup
 !blue_localization
-!blue_joy
 !blue_description
+!blue_demos
 !blue.repos
 !.docker/entrypoints
 !requirements-build.txt
-!requirements-dev.txt

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,12 +1,3 @@
-# Checklist
-
-- [ ] I have performed a thorough review of my code
-- [ ] I have sufficiently commented my code
-- [ ] The implementation follows the project style conventions
-- [ ] All project unit tests are passing
-- [ ] If relevant, documentation has been provided or updated to discuss the changes made
-- [ ] System integration tests were performed successfully
-
 ## Changes Made
 
 Please provide a description of all changes made in this PR and why the changes

.pre-commit-config.yaml

@@ -1,21 +1,10 @@
 repos:
-  - repo: https://github.com/psf/black
-    rev: 23.1.0
-    hooks:
-      - id: black
-
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.0.291
     hooks:
       - id: ruff
         args: ["--fix", "--exit-non-zero-on-fix"]
 
-  - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.4
-    hooks:
-      - id: codespell
-        args: ["--write-changes"]
-
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:

.vscode/settings.json

@@ -32,16 +32,6 @@
     "/opt/ros/iron/local/lib/python3.10/dist-packages/",
     "${workspaceFolder}/install/"
   ],
-  "C_Cpp.default.intelliSenseMode": "linux-gcc-x86",
-  "C_Cpp.clang_format_fallbackStyle": "Google",
-  "C_Cpp.codeAnalysis.clangTidy.enabled": true,
-  "C_Cpp.codeAnalysis.clangTidy.codeAction.formatFixes": true,
-  "clang-format.executable": "/usr/bin/clang-format-14",
-  "[cpp]": {
-    "editor.rulers": [120],
-    "editor.tabSize": 2,
-    "editor.defaultFormatter": "xaver.clang-format"
-  },
   "[python]": {
     "editor.tabSize": 4,
     "editor.rulers": [90],
@@ -50,7 +40,7 @@
       "source.fixAll": "explicit",
       "source.organizeImports": "explicit"
     },
-    "editor.defaultFormatter": "ms-python.black-formatter"
+    "editor.defaultFormatter": "charliermarsh.ruff"
   },
   "[dockerfile]": {
     "editor.quickSuggestions": {
@@ -65,13 +55,10 @@
   "[xml]": {
     "editor.defaultFormatter": "redhat.vscode-xml"
   },
-  "[markdown]": {
-    "editor.rulers": [80],
-    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
-  },
   "search.exclude": {
     "**/build": true,
     "**/install": true,
     "**/log": true
-  }
+  },
+  "python.analysis.typeCheckingMode": "basic"
 }

README.md

@@ -1,61 +1,33 @@
 # Blue :ocean:
 
-Blue is an end-to-end ROS 2 pipeline designed to support development,
-testing, and deployment of underwater robots.
+Blue is an ROS 2 pipeline designed to support development, testing, and
+deployment of underwater vehicles. To get started with Blue, please refer to
+the project [documentation](https://robotic-decision-making-lab.github.io/blue/).
 
 ## Main Features
 
 The main features of Blue include:
 
-- A set of interfaces designed to enable development of custom localization,
-  planning, and control algorithms alongside the existing implemented algorithms
-  (e.g., integral sliding mode control)
-- A collection of commonly-used underwater vehicle models (both visual and
-  hydrodynamic) like the [Blue Robotics](https://bluerobotics.com/) BlueROV2
-  and the BlueROV2 Heavy with support for developing your own custom models
-- ArduSub + Gazebo SITL integration for evaluating the performance of your
-  algorithms in a simulation environment
-- Docker integration to support deployment of your algorithms to hardware
+- Support for 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)
+- Vehicle models and configurations for simulation using Gazebo
+- CI/CD pipelines to help you deploy your software in the same environment
+  that you performed development and testing in
+- A development environment that includes many of the tools that you need to
+  develop software for underwater vehicles
 
-## Installation
+## Citation
 
-Blue is currently supported on Linux, and is available for the ROS
-distributions Humble, Iron, and Rolling. To install Blue, first clone this
-project to the `src` directory of your ROS workspace, replacing `$ROS_DISTRO`
-with the desired ROS distribution or `main` for Rolling:
+If you find Blue to be helpful in your work, please consider citing our
+paper:
 
-```bash
-git clone -b $ROS_DISTRO git@github.com:Robotic-Decision-Making-Lab/blue.git
 ```
-
-After cloning the project, install all external dependencies using `vcs`:
-
-```bash
-vcs import src < src/blue/blue.repos
-```
-
-Finally, install the ROS dependencies using `rosdep`, again, replacing
-`$ROS_DISTRO` with the desired ROS distribution:
-
-```bash
-rosdep update && \
-rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO
-```
-
-## Quick start
-
-ROS 2 launch files have been provided to start Blue. To launch the simulation
-environment for the BlueROV2 Heavy, run
-
-```bash
-ros2 launch blue_bringup bluerov2_heavy.launch.py use_sim:=true
-```
-
-A full description of the launch arguments and their respective default values
-can be obtained by running the following command:
-
-```bash
-ros2 launch blue_bringup bluerov2_heavy.launch.py --show-args
+@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}
+}
 ```
 
 ## Getting help

blue_bringup/CMakeLists.txt

@@ -1,13 +1,7 @@
 cmake_minimum_required(VERSION 3.8)
 project(blue_bringup)
 
-set(THIS_PACKAGE_INCLUDE_DEPENDS
-  ament_cmake
-)
-
-foreach(Dependency IN ITEMS ${THIS_PACKAGE_INCLUDE_DEPENDS})
-  find_package(${Dependency} REQUIRED)
-endforeach()
+find_package(ament_cmake REQUIRED)
 
 install(
   DIRECTORY launch

blue_bringup/launch/bluerov2/bluerov2.launch.yaml

@@ -60,11 +60,11 @@ launch:
   # Load the description file
   - let:
       name: description_file
-      value: $(find-pkg-share blue_description)/xacro/$(var model_name)/config.xacro
+      value: $(find-pkg-share blue_description)/description/$(var model_name)/config.xacro
 
-  - let:
+  - arg:
       name: robot_description
-      value: $(command 'xacro $(var description_file) use_sim:=$(var use_sim)')
+      default: $(command 'xacro $(var description_file) use_sim:=$(var use_sim)')
 
   # Nodes
   - node:

blue_bringup/launch/bluerov2_heavy/bluerov2_heavy.launch.yaml

@@ -60,11 +60,11 @@ launch:
   # Load the description file
   - let:
       name: description_file
-      value: $(find-pkg-share blue_description)/xacro/$(var model_name)/config.xacro
+      value: $(find-pkg-share blue_description)/description/$(var model_name)/config.xacro
 
-  - let:
+  - arg:
       name: robot_description
-      value: $(command 'xacro $(var description_file) use_sim:=$(var use_sim)')
+      default: $(command 'xacro $(var description_file) use_sim:=$(var use_sim)')
 
   # Nodes
   - node:

blue_bringup/launch/bluerov2_heavy_reach/bluerov2_heavy_reach.launch.yaml

@@ -60,11 +60,11 @@ launch:
   # Load the description file
   - let:
       name: description_file
-      value: $(find-pkg-share blue_description)/xacro/$(var model_name)/config.xacro
+      value: $(find-pkg-share blue_description)/description/$(var model_name)/config.xacro
 
-  - let:
+  - arg:
       name: robot_description
-      value: $(command 'xacro $(var description_file) use_sim:=$(var use_sim)')
+      default: $(command 'xacro $(var description_file) use_sim:=$(var use_sim)')
 
   # Nodes
   - node:

blue_bringup/launch/bluerov2_heavy_reach/thrusters.launch.yaml

@@ -46,4 +46,3 @@ launch:
       exec: static_transform_publisher
       name: base_link_to_thruster8
       args: --x -0.118 --y 0.215 --z 0.064 --frame-id base_link --child-frame-id thruster8
-

blue_bringup/package.xml

@@ -14,9 +14,7 @@
 
   <author>Evan Palmer</author>
 
-  <exec_depend>mavros</exec_depend>
-  <exec_depend>mavros_extras</exec_depend>
-  <exec_depend>ros2launch</exec_depend>
+  <exec_depend>blue_description</exec_depend>
 
   <export>
     <build_type>ament_cmake</build_type>

blue_demos/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.8)
+project(blue_demos)
+
+find_package(ament_cmake REQUIRED)
+
+install(
+  DIRECTORY control_integration/launch
+            control_integration/config
+            control_integration/description
+  DESTINATION share/blue_demos/control_integration
+)
+
+install(
+  DIRECTORY teleoperation/launch
+            teleoperation/config
+  DESTINATION share/blue_demos/teleoperation
+)
+
+ament_package()