From ba6f4d0b3d886f923b0849143be0fba5f0a993ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Mart=C3=ADn=20Rico?= Date: Sun, 9 Aug 2026 11:14:44 +0200 Subject: [PATCH] Update Tutorials setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Francisco Martín Rico --- developer_guide/index.rst | 2 +- howtos/bonxai_navmap_from_rosbag.rst | 32 +++++++++++++ howtos/costmap_mapping.rst | 29 ++++++------ howtos/costmap_multirobot.rst | 54 ++++++++++++++++------ howtos/costmap_navigating.rst | 46 +++++++++++++----- howtos/costmap_navigating_with_icreate.rst | 14 ++++-- howtos/custom_perception_plugin.rst | 40 ++++++++++------ howtos/docker_crossdistro.rst | 9 ++++ howtos/gridmap_mapping.rst | 48 ++++++++++++------- howtos/gridmap_navigating.rst | 46 ++++++++++++------ howtos/index.rst | 14 +----- howtos/patrolling_behavior.rst | 48 +++++++++++++++---- howtos/ros2_easynav_cli.rst | 4 ++ howtos/routes_costmap_manager.rst | 33 +++++++++++++ howtos/serest_controller.rst | 7 +++ howtos/simple_mapping.rst | 25 ++++++---- howtos/simple_navigating.rst | 44 +++++++++++++++++- plugins/index.rst | 23 +++++---- 18 files changed, 388 insertions(+), 130 deletions(-) diff --git a/developer_guide/index.rst b/developer_guide/index.rst index d10857a..beba3ea 100644 --- a/developer_guide/index.rst +++ b/developer_guide/index.rst @@ -1,4 +1,4 @@ -.. developer_guide: +.. _developer_guide: ================ Developers Guide diff --git a/howtos/bonxai_navmap_from_rosbag.rst b/howtos/bonxai_navmap_from_rosbag.rst index f640a9b..64720f6 100644 --- a/howtos/bonxai_navmap_from_rosbag.rst +++ b/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--easynav-bonxai-maps-manager \ + ros--easynav-navmap-maps-manager + +- **Pixi**: + + .. code-block:: bash + + pixi add \ + ros--easynav-bonxai-maps-manager \ + ros--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 -------- diff --git a/howtos/costmap_mapping.rst b/howtos/costmap_mapping.rst index b33efaf..0d816ad 100644 --- a/howtos/costmap_mapping.rst +++ b/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--easynav-costmap-maps-manager`` +- **Pixi**: ``pixi add ros--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 -------- diff --git a/howtos/costmap_multirobot.rst b/howtos/costmap_multirobot.rst index 70ea3c5..d887b55 100644 --- a/howtos/costmap_multirobot.rst +++ b/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--easynav-simple-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-maps-manager \ + ros--easynav-costmap-planner + +- **Pixi**: + + .. code-block:: bash + + pixi add \ + ros--easynav-simple-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-maps-manager \ + ros--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. diff --git a/howtos/costmap_navigating.rst b/howtos/costmap_navigating.rst index 5f7b2b4..f21c7bb 100644 --- a/howtos/costmap_navigating.rst +++ b/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--easynav-serest-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-maps-manager \ + ros--easynav-costmap-planner - .. code-block:: bash +- **Pixi**: + + .. code-block:: bash + + pixi add \ + ros--easynav-serest-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-maps-manager \ + ros--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.)* diff --git a/howtos/costmap_navigating_with_icreate.rst b/howtos/costmap_navigating_with_icreate.rst index c44f982..1405f88 100644 --- a/howtos/costmap_navigating_with_icreate.rst +++ b/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:** diff --git a/howtos/custom_perception_plugin.rst b/howtos/custom_perception_plugin.rst index cc7085e..645ef12 100644 --- a/howtos/custom_perception_plugin.rst +++ b/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 ```` 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 https://github.com/EasyNavigation/EasyNavigation.git + git clone -b 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//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 diff --git a/howtos/docker_crossdistro.rst b/howtos/docker_crossdistro.rst index 2ef1b0b..76fee7c 100644 --- a/howtos/docker_crossdistro.rst +++ b/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--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) diff --git a/howtos/gridmap_mapping.rst b/howtos/gridmap_mapping.rst index 5a97645..dfd7deb 100644 --- a/howtos/gridmap_mapping.rst +++ b/howtos/gridmap_mapping.rst @@ -36,17 +36,37 @@ and planner. Setup ------ -Before starting, ensure 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 +install the **NavMap Maps Manager** and/or **Bonxai Maps Manager**, depending on +which representation you want to build: -1. You have completed the installation described in :doc:`../build_install/index`. -2. You have a working workspace containing the following repositories: +- **APT**: - - ``EasyNavigation`` (provides ``easynav_system``, ``easynav_sensors``, etc.) - - ``easynav_plugins`` (provides ``easynav_navmap_maps_manager`` and ``easynav_bonxai_maps_manager``) - - ``NavMap`` (the core NavMap library and ROS message/conversion utilities) - - ``easynav_playground_summit`` *(for the Summit simulation world, if you want an outdoor scene)* - - A SLAM package of your choice able to publish a map as a ``sensor_msgs/msg/PointCloud2`` - (this workspace does not currently bundle a specific outdoor LiDAR-SLAM integration). + .. code-block:: bash + + sudo apt install ros--easynav-navmap-maps-manager # NavMap + sudo apt install ros--easynav-bonxai-maps-manager # Bonxai + +- **Pixi**: + + .. code-block:: bash + + pixi add ros--easynav-navmap-maps-manager # NavMap + pixi add ros--easynav-bonxai-maps-manager # Bonxai + +- **Source**: already built if you followed :ref:`build_from_source` (that step + clones ``NavMap`` alongside ``EasyNavigation``/``easynav_plugins``, which is what + provides the NavMap core library and ROS conversion utilities). + +You will also need, cloned into ``~/easynav_ws/src`` (source-only, not on APT/Pixi): + +- ``easynav_playground_summit`` — provides the Summit simulator used in + :ref:`Step 1 ` below; **required** unless you already have + a robot or recorded data providing a live point-cloud feed. +- A SLAM package of your choice able to publish a map as a + ``sensor_msgs/msg/PointCloud2`` (this workspace does not currently bundle a + specific outdoor LiDAR-SLAM integration). .. warning:: @@ -55,13 +75,7 @@ Before starting, ensure that: ``easynav_lidarslam_ros2``, those packages are not part of the current EasyNav plugin ecosystem — use NavMap/Bonxai instead, as described below. -3. All packages build successfully and are sourced: - - .. code-block:: bash - - cd ~/ros/ros2/easynav_ws - colcon build --symlink-install - source install/setup.bash +Then source your workspace as described in :ref:`gs_source_workspace`. 4. **RViz2** is installed for visualization. 5. Simulation nodes use ``use_sim_time: true``. @@ -87,6 +101,8 @@ The workflow consists of: --- +.. _gridmap_mapping_step1: + 1. Start the Simulator ---------------------- diff --git a/howtos/gridmap_navigating.rst b/howtos/gridmap_navigating.rst index 1694991..73c997a 100644 --- a/howtos/gridmap_navigating.rst +++ b/howtos/gridmap_navigating.rst @@ -63,32 +63,50 @@ representing non-flat terrain in EasyNav. Setup ----- -1. You have completed the installation described in :doc:`../build_install/index`. -2. You have a working workspace containing the following repositories: +Complete the installation steps in :doc:`../build_install/index` first (any of APT, +Pixi or source). This tutorial's example configuration uses the **NavMap Maps +Manager**, **NavMap Planner**, **NavMap Localizer** and **SeReST Controller** +plugins, which the core ``easynav`` package does not include: - - ``EasyNavigation`` - - ``easynav_plugins`` (provides ``easynav_navmap_maps_manager``, ``easynav_navmap_planner``, - ``easynav_navmap_localizer``, ``easynav_serest_controller``) - - ``easynav_indoor_testcase`` *(for the example configuration and maps used below)* - - ``easynav_playground_kobuki`` *(for the simulated robot used below)* +- **APT**: -If something is missing, clone the required repositories: + .. code-block:: bash + + sudo apt install \ + ros--easynav-navmap-maps-manager \ + ros--easynav-navmap-planner \ + ros--easynav-navmap-localizer \ + ros--easynav-serest-controller + +- **Pixi**: + + .. code-block:: bash + + pixi add \ + ros--easynav-navmap-maps-manager \ + ros--easynav-navmap-planner \ + ros--easynav-navmap-localizer \ + ros--easynav-serest-controller + +- **Source**: already built if you followed :ref:`build_from_source` (which also + clones ``NavMap``, needed by the NavMap plugins). + +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 ~/ros/ros2/easynav_ws/src - git clone https://github.com/EasyNavigation/easynav_plugins.git + 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 your workspace: +Then build and source your workspace as described in :ref:`gs_source_workspace`: .. code-block:: bash - cd ~/ros/ros2/easynav_ws + cd ~/easynav_ws rosdep install --from-paths src --ignore-src -r -y colcon build --symlink-install - source install/setup.bash --- @@ -222,7 +240,7 @@ Launch EasyNav with: .. code-block:: bash ros2 run easynav_system system_main \ - --ros-args --params-file ~/ros/ros2/easynav_ws/src/easynav_indoor_testcase/robots_params/navmap.kobuki.params.yaml + --ros-args --params-file ~/easynav_ws/src/easynav_indoor_testcase/robots_params/navmap.kobuki.params.yaml You should see console logs from the NavMap Maps Manager, the planner, and the AMCL-style localizer starting up. diff --git a/howtos/index.rst b/howtos/index.rst index f27f3c4..d362089 100644 --- a/howtos/index.rst +++ b/howtos/index.rst @@ -69,18 +69,8 @@ GridMap Stack gridmap_mapping gridmap_navigating -Bonxai Stack ------------- - -- :doc:`bonxai_navmap_from_rosbag` - -.. toctree:: - :hidden: - - bonxai_navmap_from_rosbag - -NavMap Stack ------------- +Bonxai / NavMap Stack +--------------------- - :doc:`bonxai_navmap_from_rosbag` diff --git a/howtos/patrolling_behavior.rst b/howtos/patrolling_behavior.rst index ae2fd34..f9a2d17 100644 --- a/howtos/patrolling_behavior.rst +++ b/howtos/patrolling_behavior.rst @@ -39,26 +39,54 @@ whichever language fits your own application. Setup ----- -Before starting, make sure you have completed the installation instructions in :doc:`../build_install/index`. +Before starting, complete the installation steps in :doc:`../build_install/index` +(any of APT, Pixi or source). The navigation stack launched below +(``costmap.serest.params.yaml``) uses the **SeReST Controller**, **Costmap +Localizer**, **Costmap Maps Manager** and **Costmap Planner** plugins, which the +core ``easynav`` package does not include: -Clone ``easynav_behaviors`` (which provides both patrolling packages) and -``easynav_indoor_testcase`` (for the simulation/config used below), alongside the core -``EasyNavigation`` packages: +- **APT**: + + .. code-block:: bash + + sudo apt install \ + ros--easynav-serest-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-maps-manager \ + ros--easynav-costmap-planner + +- **Pixi**: + + .. code-block:: bash + + pixi add \ + ros--easynav-serest-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-maps-manager \ + ros--easynav-costmap-planner + +- **Source**: already built if you cloned ``easynav_plugins`` as described in + :ref:`build_from_source`. + +``easynav_behaviors`` (which provides both patrolling packages), ``easynav_indoor_testcase`` +(simulation/config used below) and ``easynav_playground_kobuki`` (the simulator launched +below) are demo/example content and only distributed as source — clone them into +``~/easynav_ws/src`` regardless of install method: .. code-block:: bash - cd ~/ros/ros2/easynav_ws/src + cd ~/easynav_ws/src git clone https://github.com/EasyNavigation/easynav_behaviors.git git clone https://github.com/EasyNavigation/easynav_indoor_testcase.git + git clone https://github.com/EasyNavigation/easynav_playground_kobuki.git -Build and source the workspace: +Build and source the workspace as described in :ref:`gs_source_workspace`: .. code-block:: bash - cd ~/ros/ros2/easynav_ws + cd ~/easynav_ws rosdep install --from-paths src --ignore-src -r -y colcon build --symlink-install - source install/setup.bash --- @@ -113,7 +141,7 @@ Before starting the patrol, launch the Costmap-based navigation stack. .. 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 --- @@ -127,7 +155,7 @@ placeholder file). Run it directly with its own parameter file: .. code-block:: bash ros2 run easynav_patrolling_behavior patrolling_main \ - --ros-args --params-file ~/ros/ros2/easynav_ws/src/easynav_behaviors/easynav_patrolling_behavior/config/patrolling_params.yaml + --ros-args --params-file ~/easynav_ws/src/easynav_behaviors/easynav_patrolling_behavior/config/patrolling_params.yaml **Python version.** ``easynav_patrolling_behavior_py`` does ship a launch file that loads its own config automatically: diff --git a/howtos/ros2_easynav_cli.rst b/howtos/ros2_easynav_cli.rst index 7fde2be..996ffe1 100644 --- a/howtos/ros2_easynav_cli.rst +++ b/howtos/ros2_easynav_cli.rst @@ -9,6 +9,10 @@ NAME **ros2 easynav** — top-level command group providing EasyNav developer/operator utilities. +This CLI is part of ``easynav_tools``, included in the core ``easynav`` package — no +extra plugins needed. See :doc:`../build_install/index` if you have not installed +EasyNav yet (APT, Pixi or source all work). + SYNOPSIS ======== diff --git a/howtos/routes_costmap_manager.rst b/howtos/routes_costmap_manager.rst index f3d5fcd..8f0b516 100644 --- a/howtos/routes_costmap_manager.rst +++ b/howtos/routes_costmap_manager.rst @@ -20,6 +20,39 @@ The process is split in two main steps: working costmap-based scenario (e.g., the indoor testcase). Only the parts specific to routes are shown here. +Setup +----- + +Complete the installation steps in :doc:`../build_install/index` first (any of APT, +Pixi or source). The examples below use the **Costmap Maps Manager**, **Routes Maps +Manager**, **SeReST Controller**, **Costmap Localizer** and **Costmap Planner** +plugins, which the core ``easynav`` package does not include: + +- **APT**: + + .. code-block:: bash + + sudo apt install \ + ros--easynav-costmap-maps-manager \ + ros--easynav-routes-maps-manager \ + ros--easynav-serest-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-planner + +- **Pixi**: + + .. code-block:: bash + + pixi add \ + ros--easynav-costmap-maps-manager \ + ros--easynav-routes-maps-manager \ + ros--easynav-serest-controller \ + ros--easynav-costmap-localizer \ + ros--easynav-costmap-planner + +- **Source**: already built if you cloned ``easynav_plugins`` as described in + :ref:`build_from_source`. + 1) Creating routes ------------------ diff --git a/howtos/serest_controller.rst b/howtos/serest_controller.rst index 62d6dd0..e1f9e99 100644 --- a/howtos/serest_controller.rst +++ b/howtos/serest_controller.rst @@ -11,6 +11,13 @@ and behave safely around dynamic obstacles. It includes grouped parameters, recommended defaults, and practical “if you see X, change Y” advice. +The **SeReST Controller** (``easynav_serest_controller``) is a plugin, not part of +the core ``easynav`` package — install it with +``sudo apt install ros--easynav-serest-controller`` (APT), +``pixi add ros--easynav-serest-controller`` (Pixi), or by cloning +``easynav_plugins`` as described in :ref:`build_from_source`. See +:doc:`../build_install/index` if you have not installed EasyNav yet. + .. contents:: On this page :local: :depth: 2 diff --git a/howtos/simple_mapping.rst b/howtos/simple_mapping.rst index ab0dd46..56ed642 100644 --- a/howtos/simple_mapping.rst +++ b/howtos/simple_mapping.rst @@ -35,21 +35,30 @@ The workflow consists of: Setup ----- -Before starting, ensure you have completed :doc:`../build_install/index` and cloned the following repositories -in your workspace: +Complete the installation steps in :doc:`../build_install/index` first (any of APT, +Pixi or source). This tutorial uses the **Simple Maps Manager** plugin, which the +core ``easynav`` package does not include: -- ``EasyNavigation`` -- ``easynav_plugins`` -- ``easynav_playground_kobuki`` *(for simulation)* -- ``easynav_indoor_testcase`` *(for configuration and maps)* +- **APT**: ``sudo apt install ros--easynav-simple-maps-manager`` +- **Pixi**: ``pixi add ros--easynav-simple-maps-manager`` +- **Source**: already built if you cloned ``easynav_plugins`` as described in + :ref:`build_from_source`. -All packages should build correctly with: +You will also need the simulator and example config, 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 + +Build and source the workspace as described in :ref:`gs_source_workspace`: .. code-block:: bash cd ~/easynav_ws colcon build --symlink-install - source install/setup.bash --- diff --git a/howtos/simple_navigating.rst b/howtos/simple_navigating.rst index 5d41ad9..17360de 100644 --- a/howtos/simple_navigating.rst +++ b/howtos/simple_navigating.rst @@ -20,9 +20,51 @@ Overview -This tutorial assumes you already have a map created with SLAM Toolbox or another mapping method. +This tutorial assumes you already have a map created with SLAM Toolbox or another mapping method. If you have not yet generated a map, follow :doc:`simple_mapping` first. +Setup +----- + +Complete the installation steps in :doc:`../build_install/index` first (any of APT, +Pixi or source). This tutorial's example configuration uses the **SeReST +Controller**, **Simple Localizer**, **Simple Maps Manager** and **Simple Planner** +plugins, which the core ``easynav`` package does not include: + +- **APT**: + + .. code-block:: bash + + sudo apt install \ + ros--easynav-serest-controller \ + ros--easynav-simple-localizer \ + ros--easynav-simple-maps-manager \ + ros--easynav-simple-planner + +- **Pixi**: + + .. code-block:: bash + + pixi add \ + ros--easynav-serest-controller \ + ros--easynav-simple-localizer \ + ros--easynav-simple-maps-manager \ + ros--easynav-simple-planner + +- **Source**: already built if you cloned ``easynav_plugins`` as described in + :ref:`build_from_source`. + +You will also need the simulator and example config, 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 + +Build and source the workspace as described in :ref:`gs_source_workspace`. + Once you have your map, save the resulting ``.map`` file (the Simple Maps Manager's own text format, produced by its ``savemap`` service) in any package within your workspace, such as ``easynav_indoor_testcase/maps``. diff --git a/plugins/index.rst b/plugins/index.rst index 0cd29dd..779b1f2 100644 --- a/plugins/index.rst +++ b/plugins/index.rst @@ -17,22 +17,25 @@ Each plugin resides in its own ROS 2 package and is registered through ``pluginl Supported ROS 2 versions ------------------------ -- **ROS 2 jazzy** (Ubuntu 24.04) -- **ROS 2 kilted** (Ubuntu 24.04, recommended) - **ROS 2 rolling** -- **ROS 2 humble** (Ubuntu 22.04) +- **ROS 2 lyrical** +- **ROS 2 kilted** (recommended) +- **ROS 2 jazzy** -.. image:: https://img.shields.io/badge/ROS%202-jazzy-blue - :alt: ROS 2 jazzy +See :doc:`../build_install/index` for the full install matrix (APT, Pixi, or source) +per distro. + +.. image:: https://img.shields.io/badge/ROS%202-rolling-blue + :alt: ROS 2 rolling + :target: # +.. image:: https://img.shields.io/badge/ROS%202-lyrical-blue + :alt: ROS 2 lyrical :target: # .. image:: https://img.shields.io/badge/ROS%202-kilted-blue :alt: ROS 2 kilted :target: # -.. image:: https://img.shields.io/badge/ROS%202-rolling-blue - :alt: ROS 2 rolling - :target: # -.. image:: https://img.shields.io/badge/ROS%202-humble-blue - :alt: ROS 2 humble +.. image:: https://img.shields.io/badge/ROS%202-jazzy-blue + :alt: ROS 2 jazzy :target: # .. image:: https://github.com/EasyNavigation/easynav_plugins/actions/workflows/rolling.yaml/badge.svg