Update cruft

Author: apockill

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/UrbanMachine/create-ros-app.git",
-  "commit": "8c8e34317b3cf0db5459958d7a50accfd0cc93cd",
+  "commit": "340d2e1a720c27568b2729fa4ae27a1a28a08335",
   "checkout": null,
   "context": {
     "cookiecutter": {

.gitignore

@@ -23,4 +23,7 @@ __pycache__/
 .docker_volumes
 
 # URDF
-*.part
+*.part
+
+# Dev specific overrides
+*.override.yaml

docker-compose.yaml

@@ -24,7 +24,7 @@ services:
       # Mounts the 'launch-profiles/LAUNCH_PROFILE' directory into '/robot/launch-profile/'
       # This way you can save configuration files from GUI's like rviz right back to your source dir
       # LAUNCH_PROFILE is set in docker/_shared.sh
-      - "./launch-profiles/${LAUNCH_PROFILE}:/robot/launch-profile/"
+      - ./launch-profiles/${LAUNCH_PROFILE:- ''}:/robot/launch-profile
       # Necessary for display passthrough
       - "/tmp/.X11-unix:/tmp/.X11-unix:rw"
       # Necessary for PulseAudio passthrough

docker/Dockerfile

@@ -41,7 +41,6 @@ RUN --mount=type=cache,target="${APT_CACHE}" \
     # ROS2
     ros-${ROS2_DISTRO}-ros-base \
     ros-${ROS2_DISTRO}-rosbridge-suite \
-    ros-${ROS2_DISTRO}-rmw-cyclonedds-cpp \
     # Build tools
     build-essential \
     git \
@@ -98,7 +97,21 @@ COPY pkgs/node_helpers/poetry.lock pkgs/node_helpers/poetry.lock
 COPY pkgs/node_helpers/pyproject.toml pkgs/node_helpers/pyproject.toml
 ######################################################################
 
-# Install Poetry dependencies for each package
+######################################################################
+########## Add Git ROS2 Packages
+########## NOTE TO TEMPLATE USERS: If you need to depend on a package that is not in the ROS2 distro, you can add it here
+WORKDIR /ros-git-deps/
+RUN --mount=type=cache,target="${PIP_CACHE}" \
+    --mount=type=cache,target="${APT_CACHE}" \
+    install-ros-package-from-git \
+      https://github.com/UrbanMachine/node_helpers.git main pkgs && \
+    ##################### Add your packages here!
+    ########### install-ros-package-from-git {URL} {BRANCH} {PKGS PATH IN REPO}
+    echo "Done installing ROS2 packages from git"
+######################################################################
+
+# Install Poetry dependencies for each package in this repo
+WORKDIR /robot
 RUN --mount=type=cache,target="${PIP_CACHE}" \
     python3 -m colcon_poetry_ros.dependencies.install --base-paths pkgs
 
@@ -116,7 +129,7 @@ RUN --mount=type=cache,target="${BUILD_CACHE}" restore-build-cache
 # Build all packages, copying project files under a root `/robot/` directory in the container
 COPY ../launch-profiles /robot/launch-profiles
 COPY ../pkgs /robot/pkgs
-RUN enter-workspaces colcon build
+RUN enter-workspaces colcon build --packages-select $(ls pkgs)
 RUN add-workspace /robot/install/setup.bash
 
 # Move the build cache back into the Docker cache mount so it can be reused on

docker/grafana/grafana.ini

@@ -9,7 +9,7 @@ org_name = Main Org.
 org_role = Admin
 
 [users]
-default_theme = light
+default_theme = dark
 home_page = /d/logs_dashboard/logs
 
 [dashboards]

docker/utils/environment/install-ros-package-from-git

@@ -1,22 +1,92 @@
 #!/usr/bin/env bash
 
-# Clones a git ros2 repo, checks out a specific branch, then builds and installs it.
+# Installs ROS packages from a Git repository into the Docker image.
 #
-# Usage: install-ros-package-from-git {repo_url} {commit_hash}
+# This script:
+#  - Requires specifying the repository URL, branch/tag, and the relative path to a pkgs directory.
+#  - Clones the repository to a temporary directory.
+#  - Checks out the specified branch or tag.
+#  - Moves the contents of the given pkgs directory into a new directory (named after the repo) in the current directory.
+#  - Installs dependencies and builds all packages found in that directory.
+#
+# Usage:
+#   install-ros-package-from-git {repository_url} {branch_or_tag} {pkgs_subdir}
+#
+# Example:
+#   install-ros-package-from-git https://github.com/UrbanMachine/example_repo.git main pkgs
+#
+# This might produce a structure like:
+#   current_dir/
+#     example_repo/
+#       some_pkg_A/
+#       some_pkg_B/
 
 set -o errexit
 set -o pipefail
 set -o nounset
 
-# Get a directory name based on the URL of the git repo
-REPO_PATH=$(pwd)/$(basename "$1" .git)
+function usage {
+  echo "Usage: install-ros-package-from-git {repository_url} {branch_or_tag} {pkgs_subdir}" >&2
+  exit 1
+}
+
+function main {
+  if [[ "$#" -ne 3 ]]; then
+    usage
+  fi
+
+  local repo_url="$1"
+  local branch_or_tag="$2"
+  local pkgs_subdir="$3"
+
+  local original_dir
+  original_dir="$(pwd)"
+
+  # Derive the package name from the repo URL
+  local package_name
+  package_name="$(basename "${repo_url}" .git)"
+
+  local dest_dir="${original_dir}/${package_name}"
+  if [[ -d "${dest_dir}" ]]; then
+    echo "Directory ${dest_dir} already exists. Remove it or choose a different repository." >&2
+    exit 1
+  fi
+
+  # Create a temporary directory for cloning
+  local temp_dir
+  temp_dir="$(mktemp -d)"
+
+  # Clone the repository into the temp directory
+  git clone "${repo_url}" "${temp_dir}"
+  cd "${temp_dir}"
+
+  # Checkout the specified branch or tag
+  git checkout "${branch_or_tag}"
+
+  # Verify that the specified pkgs_subdir exists
+  if [[ ! -d "${pkgs_subdir}" ]]; then
+    echo "The specified pkgs_subdir '${pkgs_subdir}' does not exist in the repository." >&2
+    exit 1
+  fi
+
+  # Create the destination directory and move the packages
+  mkdir -p "${dest_dir}"
+  # Move everything from pkgs_subdir into the new directory
+  mv "${pkgs_subdir}"/* "${dest_dir}/"
+
+  # Return to the original directory to install dependencies and build
+  cd "${original_dir}"
+
+  # Install ROS dependencies with rosdep
+  with-package-list rosdep install -i --from-path "${dest_dir}" --rosdistro "${ROS2_DISTRO:-foxy}" -y
+
+  # Install Poetry dependencies for the packages
+  python3 -m colcon_poetry_ros.dependencies.install --base-paths "${dest_dir}"
 
-# Clone and check out the requisite stuff
-git clone "$1"
-cd "${REPO_PATH}"
-git checkout "$2"
+  # Build the packages using colcon
+  # We use enter-workspaces to ensure all previously added workspaces are sourced.
+  enter-workspaces colcon build --base-paths "${package_name}"
+  add-workspace "${original_dir}/install/setup.bash"
+}
 
-# Install dependencies, build the package, and add it to the ros2 workspaces
-with-package-list rosdep install -i --rosdistro "${ROS2_DISTRO}" -y --from-path .
-enter-workspaces colcon build
-add-workspace "${REPO_PATH}/install/setup.bash"
+main "$@"

docs/about_template.md

@@ -37,10 +37,14 @@ Here's a quick guide on the features of this template
 
 ### Things You Likely Want To Do
 
+- **Create a new package**: It's recommended to just start by developing with the example package that comes with the
+    template after generation. Once you're familiar with development with the template and want to create a second package,
+    you can follow the steps under [Adding a New Package](#adding-a-new-package).
 - **Add new dependencies:**
-  - **Python dependencies:** can be added under `pkgs/<package_name>/pyproject.toml`. Run `poetry lock` after. 
-  - **ROS dependencies:** can be added under `pkgs/<package_name>/package.xml`.
   - **System dependencies:** can be added under `docker/Dockerfile`, under the `install-packages` section.
+  - **Python dependencies:** can be added under `pkgs/<package_name>/pyproject.toml`. Run `poetry lock` after.
+  - **ROS dependencies:** can be added under `pkgs/<package_name>/package.xml`.
+  - **ROS Git dependencies:** If you need to add a ROS package that isn't available in the ROS package index, you can add it as a git dependency in the `docker/Dockerfile` under the `Add Git ROS2 Packages` section.
 
   After any changes, the container will automatically re-build on the next launch.
 - **Save persistent data:** The `/robot/persistent` directory is mounted to `.docker_volumes/ros-nodes/` on your local machine. Save data there to persist across container runs, and to view it in your file manager.
@@ -49,7 +53,34 @@ Here's a quick guide on the features of this template
   - Add a directory under `docker/launch-profiles/`
   - Add a `launching.py` file that launches your ROS nodes inside your new profile directory
   - Fill out the `launching.py` file with the nodes you want to launch.
-  
+  - The directory you created will be mounted under `/robot/launch-profile/` at launch. This is a great place to store configuration files, URDFs, and other specifics for your launch profile.
+
+
+## Container Structure
+
+### `/robot` Directory
+
+The `/robot` directory is where your source code lives after building the container.
+You can find your:
+ - `pkgs/` directory
+ - `build/`, `install/` from the colcon build
+
+### `/robot/launch-profile/` Directory
+A directory pointing towards the launch profile chosen in `docker/launch <launch profile>`
+is mounted under `/robot/launch-profile/`. 
+
+### `/robot/persistent/` Directory
+For saving persistent data, `/robot/persistent` is mounted to `.docker_volumes/ros-nodes/` on your local machine.
+This is a great place to save any serialized data, databases, etc. For static configuration,
+it's recommended to use the `launch-profile` directory.
+
+### `/ros-git-deps/` Directory
+
+In the `Dockerfile`, there's a section for adding ROS packages that aren't available in 
+the ROS package index. These are added as git dependencies. The `ros-git-deps/` 
+directory is where these packages are cloned to, and built.
+
+
 ## Project Structure
 
 ### `pkgs/`
@@ -144,4 +175,21 @@ The `/robot/persistent` directory is intended for you, the developer, to use. So
 
 The `.gitattributes` file is used to configure common binary file formats that are used in 
 robots such that git uses Large File Storage (LFS) to store them. It also specified certain
-line endings so that docker support works on windows.
+line endings so that docker support works on windows.
+
+# Adding a New Package
+
+It's recommended to start by developing with the example package that comes with the
+template after generation. Once you're familiar with development with the template and want to create a second package,
+you can follow the steps below:
+
+1. Create a new package directory under `pkgs/`
+2. Add a `package.xml` file to the package directory, follow the standard ROS2 package.xml format
+3. Create a pyproject.toml file. Follow the example in the `example_package` directory.
+4. Create a `resource` directory in the package directory, with an empty file in it called `{your package name}`
+5. Create a directory for your code in the package directory, and it's recommended to create a `{your_package_name}_test` directory as well.
+6. Add a few things to the Dockerfile:
+    - Under the `Add package.xml's of each package` section, copy the `package.xml` file into the container
+    - Under the `Add pyproject.toml's of each package` section, copy the `pyproject.toml` file into the container
+
+You should be good to go! Next time you run `docker/launch`, your new package will be built and available in the container.