Update Tutorials setup

developer_guide/index.rst

@@ -1,4 +1,4 @@
-.. developer_guide:
+.. _developer_guide:
 
 ================
 Developers Guide

howtos/bonxai_navmap_from_rosbag.rst

@@ -15,6 +15,38 @@ or ``map`` frame.
 
 ---
 
+Setup
+-----
+
+Complete the installation steps in :doc:`../build_install/index` first (any of APT,
+Pixi or source). This tutorial uses the **Bonxai Maps Manager** and **NavMap Maps
+Manager** plugins, which the core ``easynav`` package does not include:
+
+- **APT**:
+
+  .. code-block:: bash
+
+     sudo apt install \
+       ros-<distro>-easynav-bonxai-maps-manager \
+       ros-<distro>-easynav-navmap-maps-manager
+
+- **Pixi**:
+
+  .. code-block:: bash
+
+     pixi add \
+       ros-<distro>-easynav-bonxai-maps-manager \
+       ros-<distro>-easynav-navmap-maps-manager
+
+- **Source**: already built if you followed :ref:`build_from_source` (which also
+  clones ``NavMap``, needed by the NavMap Maps Manager).
+
+Then source your workspace as described in :ref:`gs_source_workspace`. You will
+also need a recorded ROS bag containing a ``PointCloud2`` map (this workspace does
+not ship one — use your own or one produced by :doc:`gridmap_mapping`).
+
+---
+
 Overview
 --------
 

howtos/costmap_mapping.rst

@@ -17,24 +17,25 @@ If you have not set up EasyNav yet, please complete the steps in :doc:`../build_
 Setup
 ------
 
-Before running this tutorial, make sure that:
+Complete the installation steps in :doc:`../build_install/index` first (any of
+APT, Pixi or source). The core ``easynav`` package does not include plugins, so
+also make sure the **Costmap Maps Manager** is installed in your ``~/easynav_ws``:
 
-1. You have a working **EasyNav workspace** (for example `~/ros/ros2/easynav_ws`) built and sourced.
-2. Ensure that the following repositories are present inside your ``src/`` folder:
+- **APT**: ``sudo apt install ros-<distro>-easynav-costmap-maps-manager``
+- **Pixi**: ``pixi add ros-<distro>-easynav-costmap-maps-manager``
+- **Source**: already built if you cloned ``easynav_plugins`` as described in
+  :ref:`build_from_source`.
 
-   - ``EasyNavigation``
-   - ``easynav_plugins``
-   - ``easynav_playground_kobuki`` *(optional, for simulation)*
-   - ``easynav_indoor_testcase`` *(optional, for maps and configuration examples)*
+You can run this tutorial either in simulation (e.g., Gazebo) or using a static map
+file/robot of your own. If you want to follow along in simulation (the easiest way
+to actually run this tutorial), also clone into ``~/easynav_ws/src``:
 
-3. Your workspace is sourced:
+- ``easynav_playground_kobuki`` — provides the simulator; **required** unless you
+  already have a robot or a static map to work from.
+- ``easynav_indoor_testcase`` *(optional)* — only used here as an example of a
+  package layout for storing maps; not required if you use your own package.
 
-   .. code-block:: bash
-
-      cd ~/ros/ros2/easynav_ws
-      source install/setup.bash
-
-You can run this tutorial either in simulation (e.g., Gazebo) or using a static map file.
+Then source your workspace as described in :ref:`gs_source_workspace`.
 
 Overview
 --------

howtos/costmap_multirobot.rst

@@ -28,21 +28,49 @@ This tutorial explains how to set up multiple robots safely without topic or TF
 Setup
 -----
 
-Before starting, make sure you have followed the installation instructions in :doc:`../build_install/index`.  
-Then ensure that your workspace includes at least:
+Before starting, complete the installation steps in :doc:`../build_install/index`
+(any of APT, Pixi or source). This tutorial's example configuration uses the
+**Simple Controller**, **Costmap Localizer**, **Costmap Maps Manager** and
+**Costmap Planner** plugins, which the core ``easynav`` package does not include:
 
-- ``EasyNavigation``  
-- ``easynav_plugins``  
-- ``easynav_playground_kobuki``  
-- ``easynav_indoor_testcase``  
+- **APT**:
 
-and that everything builds correctly:
+  .. code-block:: bash
+
+     sudo apt install \
+       ros-<distro>-easynav-simple-controller \
+       ros-<distro>-easynav-costmap-localizer \
+       ros-<distro>-easynav-costmap-maps-manager \
+       ros-<distro>-easynav-costmap-planner
+
+- **Pixi**:
+
+  .. code-block:: bash
+
+     pixi add \
+       ros-<distro>-easynav-simple-controller \
+       ros-<distro>-easynav-costmap-localizer \
+       ros-<distro>-easynav-costmap-maps-manager \
+       ros-<distro>-easynav-costmap-planner
+
+- **Source**: already built if you cloned ``easynav_plugins`` as described in
+  :ref:`build_from_source`.
+
+You will also need the demo/simulation repositories, which are only distributed
+as source — clone them into ``~/easynav_ws/src`` regardless of install method:
+
+.. code-block:: bash
+
+   cd ~/easynav_ws/src
+   git clone https://github.com/EasyNavigation/easynav_playground_kobuki.git
+   git clone https://github.com/EasyNavigation/easynav_indoor_testcase.git
+
+Then build and source the workspace as described in :ref:`gs_source_workspace`:
 
 .. code-block:: bash
 
-   cd ~/ros/ros2/easynav_ws
+   cd ~/easynav_ws
    colcon build --symlink-install
-   source install/setup.bash
 
 ---
 
@@ -142,7 +170,7 @@ Each instance uses the same parameter file but with its own namespace and TF rem
 
    ros2 run easynav_system system_main \
      --ros-args \
-     --params-file ~/ros/ros2/easynav_ws/src/easynav_indoor_testcase/robots_params/costmap_multirobot.params.yaml \
+     --params-file ~/easynav_ws/src/easynav_indoor_testcase/robots_params/costmap_multirobot.params.yaml \
      -r __ns:=r1 \
      -r /tf:=tf -r /tf_static:=tf_static
 
@@ -152,7 +180,7 @@ Each instance uses the same parameter file but with its own namespace and TF rem
 
    ros2 run easynav_system system_main \
      --ros-args \
-     --params-file ~/ros/ros2/easynav_ws/src/easynav_indoor_testcase/robots_params/costmap_multirobot.params.yaml \
+     --params-file ~/easynav_ws/src/easynav_indoor_testcase/robots_params/costmap_multirobot.params.yaml \
      -r __ns:=r2 \
      -r /tf:=tf -r /tf_static:=tf_static
 
@@ -166,11 +194,11 @@ Open one RViz window per robot namespace to visualize each navigation stack inde
 
    ros2 launch easynav_playground_kobuki rviz_namespaced.launch.py \
      namespace:=r1 use_sim_time:=true \
-     rviz_config:=~/ros/ros2/easynav_ws/src/easynav_playground_kobuki/rviz/nav2_namespaced_view.rviz
+     rviz_config:=~/easynav_ws/src/easynav_playground_kobuki/rviz/nav2_namespaced_view.rviz
 
    ros2 launch easynav_playground_kobuki rviz_namespaced.launch.py \
      namespace:=r2 use_sim_time:=true \
-     rviz_config:=~/ros/ros2/easynav_ws/src/easynav_playground_kobuki/rviz/nav2_namespaced_view.rviz
+     rviz_config:=~/easynav_ws/src/easynav_playground_kobuki/rviz/nav2_namespaced_view.rviz
 
 You can now send **2D Goal Poses** independently in each RViz instance.
 

howtos/costmap_navigating.rst

@@ -16,22 +16,44 @@ configure and run EasyNav to navigate using the generated map.
 Setup
 ------
 
-Before starting, ensure that:
+Before starting, complete the installation steps in :doc:`../build_install/index`
+(any of APT, Pixi or source). This tutorial's example configuration uses the
+**SeReST Controller**, **Costmap Localizer**, **Costmap Maps Manager** and
+**Costmap Planner** plugins, which the core ``easynav`` package does not include:
 
-1. You have completed the installation steps in :doc:`../build_install/index`.  
-2. You have cloned and built the following repositories in your workspace:
+- **APT**:
 
-   - ``EasyNavigation``
-   - ``easynav_plugins``
-   - ``easynav_playground_kobuki`` *(for simulation)*
-   - ``easynav_indoor_testcase`` *(for maps and parameter examples)*
+  .. code-block:: bash
 
-3. Your workspace is sourced:
+     sudo apt install \
+       ros-<distro>-easynav-serest-controller \
+       ros-<distro>-easynav-costmap-localizer \
+       ros-<distro>-easynav-costmap-maps-manager \
+       ros-<distro>-easynav-costmap-planner
 
-   .. code-block:: bash
+- **Pixi**:
+
+  .. code-block:: bash
+
+     pixi add \
+       ros-<distro>-easynav-serest-controller \
+       ros-<distro>-easynav-costmap-localizer \
+       ros-<distro>-easynav-costmap-maps-manager \
+       ros-<distro>-easynav-costmap-planner
+
+- **Source**: already built if you cloned ``easynav_plugins`` as described in
+  :ref:`build_from_source`.
+
+You will also need the demo/simulation repositories, which are only distributed
+as source — clone them into ``~/easynav_ws/src`` regardless of install method:
+
+.. code-block:: bash
+
+   cd ~/easynav_ws/src
+   git clone https://github.com/EasyNavigation/easynav_playground_kobuki.git
+   git clone https://github.com/EasyNavigation/easynav_indoor_testcase.git
 
-      cd ~/ros/ros2/easynav_ws
-      source install/setup.bash
+Then build and source the workspace as described in :ref:`gs_source_workspace`.
 
 ---
 
@@ -191,7 +213,7 @@ Running the Simulation
    .. code-block:: bash
 
       ros2 run easynav_system system_main \
-         --ros-args --params-file ~/ros/ros2/easynav_ws/src/easynav_indoor_testcase/robots_params/costmap.serest.params.yaml
+         --ros-args --params-file ~/easynav_ws/src/easynav_indoor_testcase/robots_params/costmap.serest.params.yaml
 
    *(You can also create a dedicated launcher file for convenience.)*
 

howtos/costmap_navigating_with_icreate.rst

@@ -5,10 +5,17 @@ Deploying EasyNav on a Real iCreate3 Robot
 ==========================================
 
 This HowTo explains how to deploy the **Costmap Stack** of EasyNavigation (EasyNav) on a real **iRobot iCreate3** robot,
-using a Raspberry Pi 4 as on-board computer and ROS 2 Kilted.  
+using a Raspberry Pi 4 as on-board computer and ROS 2 Kilted.
 It is based on the same workflow as the *Simple Stack* tutorials but adapted for **real hardware** with a graded
 **Costmap2D** environment representation.
 
+.. note::
+   This guide is written for **ROS 2 Kilted** on Ubuntu 24.04 (the Raspberry Pi's OS) and
+   builds EasyNav **from source** (see :ref:`build_from_source`). Kilted also has APT and
+   Pixi packages (see :doc:`../build_install/index`) if you would rather not build from
+   source. For a different distro, replace every ``kilted`` below with your target
+   (``rolling``, ``jazzy`` or ``lyrical``) and use the matching git branch.
+
 .. contents:: On this page
    :local:
    :depth: 2
@@ -101,7 +108,6 @@ https://docs.ros.org/en/kilted/Installation/Ubuntu-Install-Debs.html
    .. code-block:: bash
 
       sudo apt install -y openssh-server \
-          ros-kilted-rplidar-ros \
           ros-kilted-depthai ros-kilted-depthai-ros ros-kilted-depthai-ros-driver ros-kilted-depthai-bridge \
           ros-kilted-slam-toolbox \
           ros-kilted-rmw-zenoh-cpp ros-kilted-zenoh-cpp-vendor \
@@ -124,9 +130,9 @@ EasyNav Setup on the Raspberry Pi
 
    .. code-block:: bash
 
-      git clone https://github.com/EasyNavigation/easynav_plugins.git
+      git clone -b kilted https://github.com/EasyNavigation/easynav_plugins.git
       git clone https://github.com/EasyNavigation/easynav_indoor_testcase.git
-      git clone --recursive https://github.com/EasyNavigation/EasyNavigation.git
+      git clone -b kilted --recursive https://github.com/EasyNavigation/EasyNavigation.git
       git clone https://github.com/Slamtec/sllidar_ros2.git
 
 3. **Install dependencies:**

howtos/custom_perception_plugin.rst

@@ -34,26 +34,36 @@ every received sample.
 Setup
 -----
 
-Before starting, ensure that:
+Writing and compiling a new plugin requires the EasyNav headers, so this guide builds
+everything **from source** — regardless of whether you normally use APT or Pixi for
+day-to-day EasyNav use, see :ref:`build_from_source`. Replace ``<distro>`` below with
+your target ROS 2 distro (``rolling``, ``jazzy``, ``kilted`` or ``lyrical``):
 
-1. You have completed the installation steps in :doc:`../build_install/index`.
-2. You have cloned the following repositories in your workspace:
+.. code-block:: bash
 
-   .. code-block:: bash
+   mkdir -p ~/easynav_ws/src && cd ~/easynav_ws/src
+   git clone -b <distro> https://github.com/EasyNavigation/EasyNavigation.git
+   git clone -b <distro> https://github.com/EasyNavigation/easynav_plugins.git
+   git clone https://github.com/EasyNavigation/easynav_alt_imu_sensor.git
+   git clone https://github.com/EasyNavigation/easynav_indoor_testcase.git
 
-      cd ~/ros/ros2/easynav_ws/src
-      git clone https://github.com/EasyNavigation/EasyNavigation.git
-      git clone https://github.com/EasyNavigation/easynav_plugins.git
-      git clone https://github.com/EasyNavigation/easynav_alt_imu_sensor.git
-      git clone https://github.com/EasyNavigation/easynav_indoor_testcase.git
+Then build and source the workspace:
 
-3. Your workspace builds and is sourced:
+.. code-block:: bash
 
-   .. code-block:: bash
+   cd ~/easynav_ws
+   rosdep install --from-paths src --ignore-src -y -r
+   colcon build --symlink-install
+   source /opt/ros/<distro>/setup.bash
+   source install/setup.bash
 
-      cd ~/ros/ros2/easynav_ws
-      colcon build --symlink-install
-      source install/setup.bash
+The example configuration used later in this guide also exercises the **MPC
+Controller**, **NavMap Localizer**, **Bonxai Maps Manager**, **NavMap Maps Manager**
+and **NavMap Planner** plugins — all already built above since ``easynav_plugins``
+was cloned in full. (If you only need those plugins, without developing a new one,
+you can instead install them via APT/Pixi — see :doc:`../build_install/index` — but
+``easynav_alt_imu_sensor`` itself, being the subject of this tutorial, is only
+distributed as source.)
 
 ---
 
@@ -213,7 +223,7 @@ Build the plugin package:
 
 .. code-block:: bash
 
-   cd ~/ros/ros2/easynav_ws
+   cd ~/easynav_ws
    colcon build --packages-select easynav_alt_imu_sensor
    source install/setup.bash
 

howtos/docker_crossdistro.rst

@@ -24,6 +24,15 @@ We will set up a system composed of three main parts:
 .. note::
     Ensure that all machines (Robot, Docker Container, and PC) use the same **Zenoh** version to avoid protocol mismatches. The provided Dockerfile uses version **1.7.2**.
 
+.. note::
+    This example builds EasyNav **from source** inside the image using ROS 2 Rolling,
+    but the same pattern works for **jazzy**, **kilted** or **lyrical** — just change
+    the base image tag and the ``-b rolling`` branch in the ``git clone`` commands to
+    match. For jazzy/kilted/lyrical you can also skip the source build entirely and
+    replace the whole "clone + rosdep + colcon build" block with a single
+    ``apt-get install ros-<distro>-easynav`` (plus any plugin packages you need — see
+    :doc:`../build_install/index`), which makes for a much smaller image.
+
 ---
 
 Step 1: Building the Docker Image (Rolling)